Roles & Permissions API

Returns all roles defined within the tenant, including their permission sets.

Creates a new role within the tenant. Role names must be unique within the tenant. Permissions are specified as an array of resource:action strings.

{
  "name": "billing-admin",
  "description": "Manage billing and invoices",
  "permissions": ["billing:read", "billing:write", "invoices:read", "invoices:write"]
}

Returns a specific role by ID, including its permissions and user count.

Updates a role's name, description, or permissions. Users with this role will get updated permissions on their next token refresh.

{
  "name": "admin",
  "description": "Full administrative access (updated)",
  "permissions": ["users:read", "users:write", "roles:manage", "settings:write", "billing:read"]
}

Deletes a role. All users with this role will have it removed. Cannot delete a role that is the tenant's only admin role (safety check).

Replaces the entire permission set for a role. This is a full replacement — any permissions not included in the array will be removed.

{
  "permissions": ["posts:read", "posts:write", "posts:publish", "media:upload", "media:delete"]
}

Returns the full list of available permissions that can be assigned to roles. Permissions follow the resource:action format.

Performs a real-time authorization check against the user's roles, permissions, and Cedar policies. Use this when your backend needs to make a complex access decision that goes beyond simple JWT permission checks.

{
  "user_id": "usr_01H8KXYZ4F2B7NQ9RPWT3M6J",
  "action": "write",
  "resource": "posts",
  "context": {
    "department": "engineering",
    "post_status": "draft"
  }
}

What's Next