Permissions

Full SDK reference for the authorization engine including RBAC, ABAC, ReBAC, federation, and audit.

The client.permissions namespace provides typed methods for all authorization operations including permission checks, role management, ABAC policies, ReBAC relationships, module registration, federation, and audit. Available in TypeScript, Python, and Go SDKs.

SDK	Install	Namespace
TypeScript	`npm install @caldera/platformxe-sdk`	`client.permissions`
Python	`pip install platformxe`	`client.permissions`
Go	`go get github.com/calderax/platformxe-go`	`client.Permissions`

Permission checks

check

Perform a single permission check against the full authorization engine (RBAC + ABAC + ReBAC + overrides).

const result = await client.permissions.check({
  adminId: 'user_xyz789',
  path: 'articles',
  action: 'read',
  resource: { ownerId: 'user_xyz789', status: 'draft' },
  context: { ip: '102.89.23.45' },
});
// result.data.allowed: boolean
// result.data.source: string (e.g. "ROLE", "POLICY", "OVERRIDE")

result = client.permissions.check(
    admin_id="user_xyz789",
    path="articles",
    action="read",
    resource={"ownerId": "user_xyz789", "status": "draft"},
)

result, err := client.Permissions.Check("user_xyz789", "articles", "read")

checkBatch

Evaluate multiple permission checks in a single request. Returns results in the same order as the input checks.

const result = await client.permissions.checkBatch({
  adminId: 'user_xyz789',
  checks: [
    { path: 'articles', action: 'read' },
    { path: 'articles', action: 'delete' },
    { path: 'billing', action: 'read' },
  ],
});
// result.data.results: Array<{ path, action, allowed, source }>

result = client.permissions.check_batch(
    admin_id="user_xyz789",
    checks=[
        {"path": "articles", "action": "read"},
        {"path": "articles", "action": "delete"},
    ],
)

result, err := client.Permissions.CheckBatch([]map[string]interface{}{
    {"adminId": "user_xyz789", "path": "articles", "action": "read"},
    {"adminId": "user_xyz789", "path": "articles", "action": "delete"},
})

resolve

Return the full resolved permission set for a user, combining role capabilities, module permissions, and overrides.

const result = await client.permissions.resolve('user_xyz789');
// result.data.capabilities: string[]
// result.data.modules: Array<{ moduleId, actions }>
// result.data.overrides: Array<{ path, action, effect }>

result = client.permissions.resolve("user_xyz789")

result, err := client.Permissions.Resolve("user_xyz789")

shadowCheck

Compare a local permission decision against the server to detect discrepancies. Used for gradual migration to PlatformXe authorization.

const result = await client.permissions.shadowCheck({
  adminId: 'user_xyz789',
  path: 'articles',
  action: 'delete',
  localDecision: true,
});
// result.data.discrepancy: boolean
// result.data.serverDecision: boolean

result = client.permissions.shadow_check(
    admin_id="user_xyz789",
    path="articles",
    action="delete",
    local_decision=True,
)

result, err := client.Permissions.ShadowCheck(map[string]interface{}{
    "adminId":       "user_xyz789",
    "path":          "articles",
    "action":        "delete",
    "localDecision": true,
})

Roles

listRoles

const { roles } = await client.permissions.listRoles();

result = client.permissions.list_roles()

result, err := client.Permissions.ListRoles()

createRole

const role = await client.permissions.createRole({
  name: 'Editor',
  description: 'Content editor',
  model: 'SIMPLE',
});

role = client.permissions.create_role(name="Editor", description="Content editor", model="SIMPLE")

role, err := client.Permissions.CreateRole("Editor", "Content editor", "SIMPLE")

getRole

const role = await client.permissions.getRole('role_abc123');

role = client.permissions.get_role("role_abc123")

role, err := client.Permissions.GetRole("role_abc123")

updateRole

await client.permissions.updateRole('role_abc123', {
  description: 'Updated description',
});

client.permissions.update_role("role_abc123", description="Updated description")

role, err := client.Permissions.UpdateRole("role_abc123", map[string]interface{}{
    "description": "Updated description",
})

deleteRole

await client.permissions.deleteRole('role_abc123');

client.permissions.delete_role("role_abc123")

result, err := client.Permissions.DeleteRole("role_abc123")

Capabilities (Simple model)

getRoleCapabilities

const caps = await client.permissions.getRoleCapabilities('role_abc123');

caps = client.permissions.get_role_capabilities("role_abc123")

caps, err := client.Permissions.GetRoleCapabilities("role_abc123")

setRoleCapabilities

Replace the full set of capabilities for a SIMPLE model role.

await client.permissions.setRoleCapabilities('role_abc123', {
  capabilities: ['articles:read', 'articles:create', 'articles:update'],
});

client.permissions.set_role_capabilities("role_abc123", capabilities=["articles:read", "articles:create"])

caps, err := client.Permissions.SetRoleCapabilities("role_abc123", []string{"articles:read", "articles:create"})

Module permissions (Full model)

getRoleModulePermissions

const mods = await client.permissions.getRoleModulePermissions('role_abc123');

mods = client.permissions.get_role_module_permissions("role_abc123")

mods, err := client.Permissions.GetRoleModulePermissions("role_abc123")

setRoleModulePermissions

Replace the full set of module permissions for a FULL model role.

await client.permissions.setRoleModulePermissions('role_abc123', {
  modules: [
    { moduleId: 'mod_bookings', actions: ['READ', 'CREATE'] },
    { moduleId: 'mod_properties', actions: ['READ', 'UPDATE'] },
  ],
});

client.permissions.set_role_module_permissions("role_abc123", modules=[
    {"moduleId": "mod_bookings", "actions": ["READ", "CREATE"]},
])

mods, err := client.Permissions.SetRoleModulePermissions("role_abc123", []map[string]interface{}{
    {"moduleId": "mod_bookings", "actions": []string{"READ", "CREATE"}},
})

Modules

listModules

const { modules } = await client.permissions.listModules();

result = client.permissions.list_modules()

result, err := client.Permissions.ListModules()

registerModule

await client.permissions.registerModule({
  name: 'PROPERTIES',
  actions: ['READ', 'CREATE', 'UPDATE', 'DELETE'],
});

client.permissions.register_module(name="PROPERTIES", actions=["READ", "CREATE", "UPDATE", "DELETE"])

mod, err := client.Permissions.RegisterModule(map[string]interface{}{
    "name":    "PROPERTIES",
    "actions": []string{"READ", "CREATE", "UPDATE", "DELETE"},
})

Overrides

createOverride

await client.permissions.createOverride({
  adminId: 'user_xyz789',
  path: 'billing',
  action: 'delete',
  effect: 'DENY',
  reason: 'Pending audit investigation',
  expiresAt: '2026-06-01T00:00:00Z',
});

client.permissions.create_override(
    admin_id="user_xyz789", path="billing", action="delete",
    effect="DENY", reason="Pending audit investigation",
)

override, err := client.Permissions.CreateOverride(map[string]interface{}{
    "adminId": "user_xyz789", "path": "billing", "action": "delete",
    "effect": "DENY", "reason": "Pending audit investigation",
})

listOverrides

const overrides = await client.permissions.listOverrides('user_xyz789');

overrides = client.permissions.list_overrides("user_xyz789")

overrides, err := client.Permissions.ListOverrides("user_xyz789")

deleteOverride

await client.permissions.deleteOverride('ovr_abc123');

client.permissions.delete_override("ovr_abc123")

result, err := client.Permissions.DeleteOverride("ovr_abc123")

Policies (ABAC)

createPolicy

await client.permissions.createPolicy({
  name: 'Owner-only updates',
  resource: 'documents',
  action: 'update',
  effect: 'ALLOW',
  priority: 10,
  conditions: {
    all: [{ field: 'resource.ownerId', operator: 'equals', value: 'actor.id' }],
  },
});

client.permissions.create_policy(
    name="Owner-only updates", resource="documents", action="update",
    effect="ALLOW", priority=10,
    conditions={"all": [{"field": "resource.ownerId", "operator": "equals", "value": "actor.id"}]},
)

policy, err := client.Permissions.CreatePolicy(map[string]interface{}{
    "name": "Owner-only updates", "resource": "documents", "action": "update",
    "effect": "ALLOW", "priority": 10,
    "conditions": map[string]interface{}{
        "all": []map[string]interface{}{
            {"field": "resource.ownerId", "operator": "equals", "value": "actor.id"},
        },
    },
})

listPolicies

const { policies } = await client.permissions.listPolicies();

result = client.permissions.list_policies()

result, err := client.Permissions.ListPolicies()

updatePolicy

await client.permissions.updatePolicy('pol_abc123', {
  priority: 20,
  isActive: false,
});

client.permissions.update_policy("pol_abc123", priority=20, is_active=False)

policy, err := client.Permissions.UpdatePolicy("pol_abc123", map[string]interface{}{
    "priority": 20, "isActive": false,
})

deletePolicy

await client.permissions.deletePolicy('pol_abc123');

client.permissions.delete_policy("pol_abc123")

result, err := client.Permissions.DeletePolicy("pol_abc123")

Relationships (ReBAC)

writeRelationships

Create, update, or delete Zanzibar-style relationship tuples.

await client.permissions.writeRelationships({
  operations: [
    { operation: 'WRITE', subject: 'user:alice', relation: 'member', object: 'team:design' },
    { operation: 'WRITE', subject: 'user:bob', relation: 'owner', object: 'doc:report-q1' },
    { operation: 'DELETE', subject: 'user:charlie', relation: 'viewer', object: 'doc:draft' },
  ],
});

client.permissions.write_relationships(operations=[
    {"operation": "WRITE", "subject": "user:alice", "relation": "member", "object": "team:design"},
    {"operation": "DELETE", "subject": "user:charlie", "relation": "viewer", "object": "doc:draft"},
])

result, err := client.Permissions.UpdateRelationships([]map[string]interface{}{
    {"operation": "WRITE", "subject": "user:alice", "relation": "member", "object": "team:design"},
})

listRelationships

const rels = await client.permissions.listRelationships({
  subject: 'user:alice',
});

rels = client.permissions.list_relationships(subject="user:alice")

rels, err := client.Permissions.ListRelationships(map[string]string{"subject": "user:alice"})

Audit

auditDecisions

Query immutable permission decision audit logs.

const decisions = await client.permissions.auditDecisions({
  adminId: 'user_xyz789',
  from: '2026-04-01T00:00:00Z',
  to: '2026-04-13T23:59:59Z',
});

decisions = client.permissions.audit_decisions(
    admin_id="user_xyz789",
    from_date="2026-04-01T00:00:00Z",
)

decisions, err := client.Permissions.GetAuditLogs(map[string]string{
    "adminId": "user_xyz789",
    "from":    "2026-04-01T00:00:00Z",
})

auditChanges

Query permission mutation change logs (role created, policy updated, override deleted, etc.).

const changes = await client.permissions.auditChanges({
  from: '2026-04-01T00:00:00Z',
  entityType: 'ROLE',
});

changes = client.permissions.audit_changes(from_date="2026-04-01T00:00:00Z")

changes, err := client.Permissions.ListChangeLogs(map[string]string{
    "from": "2026-04-01T00:00:00Z",
})

exportAudit

Export audit logs as a downloadable file.

const result = await client.permissions.exportAudit({
  from: '2026-03-01T00:00:00Z',
  to: '2026-04-01T00:00:00Z',
  format: 'csv',
});

console.log(result.downloadUrl);

result = client.permissions.export_audit(
    from_date="2026-03-01T00:00:00Z",
    to_date="2026-04-01T00:00:00Z",
    format="csv",
)

result, err := client.Permissions.ExportAudit(map[string]string{
    "from": "2026-03-01T00:00:00Z",
    "to":   "2026-04-01T00:00:00Z",
    "format": "csv",
})

Federation (Enterprise)

Federation enables cross-application permission sharing. Enterprise tenants link their organizations into shared namespaces, pull modules, and push resolved permissions across apps.

Not to be confused with Custom Event Federation (client.events.custom.federation) — that's a Phase 9D feature that shares live tenant event traffic across peer Enterprise orgs. Different concept, different access path, different bus event prefix (FEDERATION_* here vs CUSTOM_EVENT_FEDERATION_* there).

createFederationGroup

const group = await client.permissions.createFederationGroup({
  name: 'Caldera Suite',
});

group = client.permissions.create_federation_group(name="Caldera Suite")

group, err := client.Permissions.CreateFederationGroup("Caldera Suite")

listFederationGroups

const { groups } = await client.permissions.listFederationGroups();

result = client.permissions.list_federation_groups()

result, err := client.Permissions.ListFederationGroups()

getFederationGroup

const group = await client.permissions.getFederationGroup('fg_abc123');

group = client.permissions.get_federation_group("fg_abc123")

group, err := client.Permissions.GetFederationGroup("fg_abc123")

deleteFederationGroup

await client.permissions.deleteFederationGroup('fg_abc123');

client.permissions.delete_federation_group("fg_abc123")

result, err := client.Permissions.DeleteFederationGroup("fg_abc123")

addFederationMember

await client.permissions.addFederationMember('fg_abc123', {
  organizationId: 'org_lettings_123',
  prefix: 'LT',
});

client.permissions.add_federation_member("fg_abc123", organization_id="org_lettings_123", prefix="LT")

result, err := client.Permissions.AddFederationMember("fg_abc123", map[string]interface{}{
    "organizationId": "org_lettings_123", "prefix": "LT",
})

removeFederationMember

await client.permissions.removeFederationMember('fg_abc123', 'org_lettings_123');

client.permissions.remove_federation_member("fg_abc123", "org_lettings_123")

result, err := client.Permissions.RemoveFederationMember("fg_abc123", "org_lettings_123")

pullFederationModules

Pull permission modules from the federation into the target organization.

const result = await client.permissions.pullFederationModules('fg_abc123', {
  targetOrgId: 'org_lettings_123',
});

console.log(result.modulesSynced); // 5

result = client.permissions.pull_federation_modules("fg_abc123", target_org_id="org_lettings_123")

result, err := client.Permissions.PullFederationModules("fg_abc123", "org_lettings_123")

pushFederationPermissions

Push resolved permissions for specific users to federation member organizations.

const result = await client.permissions.pushFederationPermissions('fg_abc123', {
  adminIds: ['user_001', 'user_002'],
  targetOrgId: 'org_lettings_123',
});

console.log(result.usersPushed); // 2

result = client.permissions.push_federation_permissions(
    "fg_abc123",
    admin_ids=["user_001", "user_002"],
    target_org_id="org_lettings_123",
)

result, err := client.Permissions.PushFederationPermissions("fg_abc123", []string{"user_001", "user_002"}, "org_lettings_123")

getFederationStatus

Check the sync status and health of a federation group.

const status = await client.permissions.getFederationStatus('fg_abc123');

console.log(status.lastSyncAt);
console.log(status.memberCount);
console.log(status.modulesShared);

status = client.permissions.get_federation_status("fg_abc123")

status, err := client.Permissions.GetFederationStatus("fg_abc123")

Method reference

All 35 methods in the permissions namespace:

#	Method	Description	Scope
1	`check`	Single permission check	`permissions:check`
2	`checkBatch`	Batch permission checks	`permissions:check`
3	`resolve`	Resolve full permission set	`permissions:check`
4	`shadowCheck`	Compare local vs server decision	`permissions:check`
5	`listRoles`	List all roles	`permissions:check`
6	`createRole`	Create a role	`permissions:manage`
7	`getRole`	Get a role by ID	`permissions:check`
8	`updateRole`	Update a role	`permissions:manage`
9	`deleteRole`	Delete a role	`permissions:manage`
10	`getRoleCapabilities`	Get role capabilities (Simple)	`permissions:check`
11	`setRoleCapabilities`	Set role capabilities (Simple)	`permissions:manage`
12	`getRoleModulePermissions`	Get role module permissions (Full)	`permissions:check`
13	`setRoleModulePermissions`	Set role module permissions (Full)	`permissions:manage`
14	`listModules`	List registered modules	`permissions:check`
15	`registerModule`	Register a permission module	`permissions:manage`
16	`createOverride`	Create per-user override	`permissions:manage`
17	`listOverrides`	List overrides for a user	`permissions:check`
18	`deleteOverride`	Delete an override	`permissions:manage`
19	`createPolicy`	Create an ABAC policy	`permissions:manage`
20	`listPolicies`	List all policies	`permissions:check`
21	`updatePolicy`	Update a policy	`permissions:manage`
22	`deletePolicy`	Delete a policy	`permissions:manage`
23	`writeRelationships`	Write ReBAC relationship tuples	`permissions:manage`
24	`listRelationships`	List ReBAC relationships	`permissions:check`
25	`auditDecisions`	Query decision audit logs	`permissions:audit`
26	`auditChanges`	Query mutation change logs	`permissions:audit`
27	`exportAudit`	Export audit logs	`permissions:audit`
28	`createFederationGroup`	Create federation group	`permissions:manage`
29	`listFederationGroups`	List federation groups	`permissions:check`
30	`getFederationGroup`	Get federation group	`permissions:check`
31	`deleteFederationGroup`	Delete federation group	`permissions:manage`
32	`addFederationMember`	Add member to federation	`permissions:manage`
33	`removeFederationMember`	Remove member from federation	`permissions:manage`
34	`pullFederationModules`	Pull modules from federation	`permissions:manage`
35	`pushFederationPermissions`	Push permissions to federation	`permissions:manage`

Federation methods (28-35) are restricted to Enterprise plan tenants. Calling them from a Free, Basic, or Pro API key returns a PLAN_REQUIRED error.

All permission methods require an API key with the appropriate scope: permissions:check, permissions:manage, or permissions:audit. The method reference table above shows the required scope for each method.