Permissions

GET    /orgs/{orgId}/api/v1/admin/permissions
POST   /orgs/{orgId}/api/v1/admin/permissions
GET    /orgs/{orgId}/api/v1/admin/permissions/{permissionId}
PATCH  /orgs/{orgId}/api/v1/admin/permissions/{permissionId}
DELETE /orgs/{orgId}/api/v1/admin/permissions/{permissionId}
GET    /orgs/{orgId}/api/v1/admin/permissions/{permissionId}/usage
GET    /orgs/{orgId}/api/v1/admin/scopes
POST   /orgs/{orgId}/api/v1/admin/scopes
DELETE /orgs/{orgId}/api/v1/admin/scopes/{scopeId}

Permissions are fine-grained access controls identified by a slug (e.g., repo:write). They can be assigned directly to users, groups, or roles.

Authentication

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

The Permission Object

Permission Object

{
  "id": 42,
  "slug": "repo:write",
  "name": "Write to Repository",
  "description": "Allows writing to code repositories",
  "resource": "repos",
  "action": "write",
  "isSystem": false,
  "createdAt": "2026-01-15T10:30:00Z"
}

List Permissions

List Permissions

curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/permissions?page=1&limit=50" \
  -H "Authorization: ApiKey lmk_abc123"

Query Parameters

Parameter	Description
page	Page number (default: 1)
limit	Results per page (default: 20, max: 100)
search	Filter by name, slug, or description

List Response

{
  "data": {
    "data": [{ "id": 42, "slug": "repo:write", "name": "Write to Repository" }],
    "meta": { "total": 18, "page": 1, "limit": 50, "totalPages": 1 }
  }
}

Create Permission

Create a Permission

curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/permissions \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "repo:write",
    "name": "Write to Repository",
    "description": "Allows writing to code repositories",
    "resource": "repos",
    "action": "write"
  }'

The slug must be unique within the organization and conventionally follows the pattern resource:action.

Update Permission

Update a Permission

curl -X PATCH https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/permissions/42 \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Allows writing and force-pushing to code repositories"
  }'

Get Permission Usage

Returns the roles and users that have been assigned this permission.

Get Permission Usage

curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/permissions/42/usage" \
  -H "Authorization: ApiKey lmk_abc123"

Usage Response

{
  "data": {
    "data": {
      "roles": [
        { "id": "01JF3KROLE...", "name": "developer", "slug": "developer" }
      ],
      "users": [
        { "id": "01JF3KUSER...", "email": "alice@acme.com", "name": "Alice" }
      ],
      "roleCount": 1,
      "userCount": 1
    }
  }
}

Delete Permission

Delete a Permission

curl -X DELETE "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/permissions/42" \
  -H "Authorization: ApiKey lmk_abc123"

warning

System permissions (isSystem: true) cannot be deleted.

OAuth 2.0 Scopes

Custom scopes are distinct from permissions — they are included in OAuth access tokens and control API access granted to OAuth clients.

List Scopes

List Custom Scopes

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

Create Scope

Create a Scope

curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/scopes \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "read:reports",
    "description": "Read financial reports",
    "isDefault": false
  }'

Delete Scope

Delete a Scope

curl -X DELETE "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/scopes/7" \
  -H "Authorization: ApiKey lmk_abc123"