Guides
Roles and permissions
Define per-application roles and permissions, assign them to users, and consume them in tokens.
Roles and permissions
Auth Service implements a per-application RBAC model. Each application has its own independent set of roles and permissions — a role named editor in App A is completely separate from a role named editor in App B.
All endpoints below require an admin or superadmin session.
Concepts
- Role — a named group (e.g.
editor,beta-tester) that can be assigned to users within a specific application. Each role has an optionalisDefaultflag; whentrue, new users granted access to the application receive this role automatically. - Permission — a
resource+actionpair (e.g.articles+read, orcomments+write). Permissions are attached to roles, not to users directly. - When the
rolesandpermissionsscopes are requested in an OAuth flow, Auth Service resolves the user's roles for the application, then flattens all permissions across those roles into the token.
Roles
List roles
GET /api/admin/applications/:appId/roles
Returns each role with its permissionIds array.
Create a role
POST /api/admin/applications/:appId/roles
Content-Type: application/json
{
"name": "editor",
"description": "Can create and edit content",
"isDefault": false
}
| Field | Type | Default | Description |
|---|---|---|---|
name | string | required | Role name (1–64 chars, unique per application) |
description | string | — | Optional description (max 250 chars) |
isDefault | boolean | false | Auto-assign when granting user access to the app |
Delete a role
DELETE /api/admin/applications/:appId/roles/:roleId
Returns 400 PERM_006 if any users currently hold this role within the application.
Permissions
List permissions
GET /api/admin/applications/:appId/permissions
Create a permission
POST /api/admin/applications/:appId/permissions
Content-Type: application/json
{
"resource": "articles",
"action": "write"
}
| Field | Type | Default | Description |
|---|---|---|---|
resource | string | required | Resource name — alphanumeric, dots, underscores, hyphens (1–128 chars) |
action | "read" | "write" | "read" | Access level |
The pair (resource, action) must be unique per application. Returns 409 PERM_005 on conflict.
Delete a permission
DELETE /api/admin/applications/:appId/permissions/:permissionId
Assign / unassign permissions to a role
# Assign
POST /api/admin/applications/:appId/roles/:roleId/permissions/:permissionId
# Unassign
DELETE /api/admin/applications/:appId/roles/:roleId/permissions/:permissionId
Assign a role to a user
POST /api/admin/applications/:appId/users/:userId/roles/:roleId
Unassign a role from a user
DELETE /api/admin/applications/:appId/users/:userId/roles/:roleId
Token claim format
When the roles and permissions scopes are included, the id_token carries:
{
"roles": ["editor"],
"permissions": ["articles", "comments.write"]
}
Permission strings use the format "resource" for read actions and "resource.write" for write actions. Permissions are deduplicated across all roles the user holds.