Management API

REST API for programmatic management of your realm's users, applications, roles, and API resources.

Base URL: https://your-domain.com/api/v1/{realmUUID}

Authentication

The Management API uses M2M (Machine-to-Machine) tokens. Get one via the client_credentials grant:

curl -X POST https://your-domain.com/oauth2/{realmUUID}/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=users:read users:write roles:read"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use the token in all API requests:

curl https://your-domain.com/api/v1/{realmUUID}/users \
  -H "Authorization: Bearer {access_token}"

tip

Request only the scopes you need. Available scopes: users:read, users:write, users:roles, applications:read, applications:write, roles:read, roles:write, resources:read, resources:write.

Error format

All errors return a consistent JSON structure:

{
  "error": "not_found",
  "message": "User not found"
}

Common HTTP status codes:

Code	Meaning
400	Invalid request body or parameters
401	Missing or invalid token
403	Token lacks required scope
404	Resource not found
422	Validation error

---

Users API

Base: /api/v1/{realmUUID}/users

Method	Path	Scope	Description
GET	/users	users:read	List users (paginated)
POST	/users	users:write	Create user
GET	/users/{id}	users:read	Get user by ID
PATCH	/users/{id}	users:write	Update user
DELETE	/users/{id}	users:write	Delete user
PATCH	/users/{id}/password	users:write	Change password
PATCH	/users/{id}/is-suspended	users:write	Block/unblock user
GET	/users/{id}/roles	users:roles	List user roles
POST	/users/{id}/roles	users:roles	Assign roles
DELETE	/users/{id}/roles/{roleId}	users:roles	Remove role
GET	/users/{id}/identities	users:read	Connected providers

List users

curl "https://your-domain.com/api/v1/{realmUUID}/users?page=1&per_page=20&search=john" \
  -H "Authorization: Bearer {token}"

{
  "data": [
    {
      "id": "01HQ...",
      "email": "john@example.com",
      "name": "John Doe",
      "is_suspended": false,
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 1
  }
}

Create user

curl -X POST https://your-domain.com/api/v1/{realmUUID}/users \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "name": "Jane Doe",
    "password": "securePassword123"
  }'

Update user

curl -X PATCH https://your-domain.com/api/v1/{realmUUID}/users/{id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Smith"}'

Change password

curl -X PATCH https://your-domain.com/api/v1/{realmUUID}/users/{id}/password \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"password": "newSecurePassword456"}'

Block/unblock user

curl -X PATCH https://your-domain.com/api/v1/{realmUUID}/users/{id}/is-suspended \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"is_suspended": true}'

Assign roles to user

curl -X POST https://your-domain.com/api/v1/{realmUUID}/users/{id}/roles \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"role_ids": ["role-uuid-1", "role-uuid-2"]}'

Remove role from user

curl -X DELETE https://your-domain.com/api/v1/{realmUUID}/users/{id}/roles/{roleId} \
  -H "Authorization: Bearer {token}"

---

Applications API

Base: /api/v1/{realmUUID}/applications

Method	Path	Scope	Description
GET	/applications	applications:read	List applications
POST	/applications	applications:write	Create application
GET	/applications/{id}	applications:read	Get application
PATCH	/applications/{id}	applications:write	Update application
DELETE	/applications/{id}	applications:write	Delete application
GET	/applications/{id}/roles	applications:read	List app roles
POST	/applications/{id}/roles	applications:write	Assign roles
DELETE	/applications/{id}/roles/{roleId}	applications:write	Remove role

Create application

curl -X POST https://your-domain.com/api/v1/{realmUUID}/applications \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My SPA",
    "type": "spa",
    "redirect_uris": ["https://myapp.com/callback"]
  }'

{
  "data": {
    "id": "01HQ...",
    "name": "My SPA",
    "type": "spa",
    "client_id": "abc123",
    "redirect_uris": ["https://myapp.com/callback"],
    "created_at": "2026-01-15T10:30:00Z"
  }
}

Assign roles to application

curl -X POST https://your-domain.com/api/v1/{realmUUID}/applications/{id}/roles \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"role_ids": ["role-uuid-1"]}'

---

Roles API

Base: /api/v1/{realmUUID}/roles

Method	Path	Scope	Description
GET	/roles	roles:read	List roles
POST	/roles	roles:write	Create role
GET	/roles/{id}	roles:read	Get role
PATCH	/roles/{id}	roles:write	Update role
DELETE	/roles/{id}	roles:write	Delete role
GET	/roles/{id}/scopes	roles:read	List role scopes
POST	/roles/{id}/scopes	roles:write	Assign scopes
DELETE	/roles/{id}/scopes/{scopeId}	roles:write	Remove scope

Create role

curl -X POST https://your-domain.com/api/v1/{realmUUID}/roles \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "editor",
    "description": "Can edit content"
  }'

Assign scopes to role

curl -X POST https://your-domain.com/api/v1/{realmUUID}/roles/{id}/scopes \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"scope_ids": ["scope-uuid-1", "scope-uuid-2"]}'

---

Resources API

Base: /api/v1/{realmUUID}/resources

Method	Path	Scope	Description
GET	/resources	resources:read	List API resources
POST	/resources	resources:write	Create resource
GET	/resources/{id}	resources:read	Get resource
PATCH	/resources/{id}	resources:write	Update resource
DELETE	/resources/{id}	resources:write	Delete resource
GET	/resources/{id}/scopes	resources:read	List resource scopes
POST	/resources/{id}/scopes	resources:write	Add scope
PATCH	/resources/{id}/scopes/{scopeId}	resources:write	Update scope
DELETE	/resources/{id}/scopes/{scopeId}	resources:write	Remove scope

Create API resource

curl -X POST https://your-domain.com/api/v1/{realmUUID}/resources \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API",
    "indicator": "https://api.myapp.com"
  }'

{
  "data": {
    "id": "01HQ...",
    "name": "My API",
    "indicator": "https://api.myapp.com",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

Add scope to resource

curl -X POST https://your-domain.com/api/v1/{realmUUID}/resources/{id}/scopes \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "read:posts",
    "description": "Read blog posts"
  }'

Update scope

curl -X PATCH https://your-domain.com/api/v1/{realmUUID}/resources/{id}/scopes/{scopeId} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"description": "Read all blog posts"}'