Skip to main content

Roles

GET    /orgs/{orgId}/api/v1/admin/roles
POST   /orgs/{orgId}/api/v1/admin/roles
GET    /orgs/{orgId}/api/v1/admin/roles/{roleId}
PUT    /orgs/{orgId}/api/v1/admin/roles/{roleId}
DELETE /orgs/{orgId}/api/v1/admin/roles/{roleId}
GET    /orgs/{orgId}/api/v1/admin/roles/{roleId}/permissions
POST   /orgs/{orgId}/api/v1/admin/roles/{roleId}/permissions
DELETE /orgs/{orgId}/api/v1/admin/roles/{roleId}/permissions/{permissionId}
GET    /orgs/{orgId}/api/v1/admin/roles/{roleId}/users
POST   /orgs/{orgId}/api/v1/admin/roles/{roleId}/users
DELETE /orgs/{orgId}/api/v1/admin/roles/{roleId}/users/{userId}

Roles group permissions together and can be assigned to users or groups. When a user authenticates, their active roles are embedded in the access token.

Authentication​

All role management endpoints require a valid admin API key or a Bearer token issued to a user with settings.manage permission.

The Role Object​

Role Object
{
  "id": "01JF3KABCDE...",
  "name": "developer",
  "slug": "developer",
  "description": "Can read and write code repositories",
  "permissions": ["repo:read", "repo:write", "pipeline:trigger"],
  "userCount": 12,
  "isSystem": false,
  "createdAt": "2026-01-15T10:30:00Z",
  "updatedAt": "2026-03-01T08:00:00Z"
}

List Roles​

List Roles
curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/roles" \
  -H "Authorization: ApiKey lmk_abc123"

Query Parameters​

ParameterDescription
pagePage number (default: 1)
limitResults per page (default: 20, max: 100)
searchFilter by name or slug

Create Role​

Create a Role
curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/roles \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "developer",
    "slug": "developer",
    "description": "Can read and write code repositories"
  }'

Returns 201 Created with the new role object.

Update Role​

Update a Role
curl -X PUT https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/roles/01JF3KABCDE... \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "developer",
    "description": "Read and write code repositories and trigger pipelines"
  }'

Manage Role Permissions​

Get Role Permissions​

Get Role Permissions
curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/roles/01JF3KABCDE.../permissions" \
  -H "Authorization: ApiKey lmk_abc123"

Add a Permission to a Role​

Accepts a single permissionId or an array permissionIds for bulk assignment.

Add a Permission to a Role
curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/roles/01JF3KABCDE.../permissions \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{"permissionId": 42}'
Bulk Assign Permissions
curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/roles/01JF3KABCDE.../permissions \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{"permissionIds": [42, 43, 44]}'

Remove a Permission from a Role​

Remove a Permission from a Role
curl -X DELETE "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/roles/01JF3KABCDE.../permissions/42" \
  -H "Authorization: ApiKey lmk_abc123"

Manage Role Members​

List Users in Role​

List Users with a Role
curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/roles/01JF3KABCDE.../users" \
  -H "Authorization: ApiKey lmk_abc123"

Add a User to a Role​

Add a User to a Role
curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/roles/01JF3KABCDE.../users \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{"userId": "01JF3KUSER..."}'

Remove a User from a Role​

Remove a User from a Role
curl -X DELETE "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/roles/01JF3KABCDE.../users/01JF3KUSER..." \
  -H "Authorization: ApiKey lmk_abc123"

Delete Role​

Delete a Role
curl -X DELETE "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/roles/01JF3KABCDE..." \
  -H "Authorization: ApiKey lmk_abc123"

Returns 200 on success. The role is removed from all users and groups that held it.

warning

System roles (isSystem: true) cannot be deleted.