Authentication and Authorization

Authentication Methods

All Admin APIs use Bearer token authentication. Include the admin API token in the Authorization header:

curl -X GET "https://{tenant-domain}/api/admin/users" \
  -H "Authorization: Bearer {admin-api-token}"

API Categories

The Admin API is divided into two main categories based on the target database:

Admin Console APIs (DB_ADMIN)

Admin User Management (/api/admin/admins/*)
Admin Role Management (/api/admin/admin-roles/*)
IP Allowlist (/api/admin/ip-allowlist/*)
Admin Audit Log (/api/admin/admin-audit-log/*)

EndUser Management APIs (DB_CORE)

EndUser Management (/api/admin/users/*)
Session Management (/api/admin/sessions/*)
Client Management (/api/admin/clients/*)
Access Control APIs (roles, organizations, policies, etc.)
Audit & Compliance APIs

Obtaining Admin API Tokens

Admin API tokens can be issued from the admin console:

Log in to the admin console
Navigate to “Settings” → “API Tokens”
Click “Create New Token”
Set the token name and expiration
Select the required permission scopes
Generate the token and store it securely

Role Hierarchy

Admin API permissions are based on a hierarchical role model. Higher roles have all permissions of lower roles.

system_admin (System Administrator)
    ↓
distributor_admin (Distributor Administrator)
    ↓
tenant_admin (Tenant Administrator)
    ↓
user (Regular User)

Permissions by Role

Role	Description	Main Permissions
`system_admin`	System-wide administrator	Manage all tenants, system settings
`distributor_admin`	Distributor administrator	Manage subordinate tenants, create tenants
`tenant_admin`	Tenant administrator	All management operations within tenant
`user`	Regular user	Manage own account only

Permission Scopes

Fine-grained permission scopes can be assigned to API tokens:

User Management Scopes

Scope	Description
`users:read`	Read user information
`users:write`	Create/update users
`users:delete`	Delete users
`users:suspend`	Suspend/unsuspend users

Client Management Scopes

Scope	Description
`clients:read`	Read client information
`clients:write`	Create/update clients
`clients:delete`	Delete clients
`clients:secrets`	Manage client secrets

Access Control Scopes

Scope	Description
`roles:read`	Read role information
`roles:write`	Create/update/delete roles
`roles:assign`	Assign roles
`policies:read`	Read policies
`policies:write`	Create/update/delete policies

Audit & Compliance Scopes

Scope	Description
`audit:read`	Read audit logs
`compliance:read`	Read compliance information
`compliance:write`	Execute access reviews

Authorization Errors

If permissions are insufficient, the API returns the following errors:

401 Unauthorized

When authentication credentials are not provided or invalid:

{
  "error": "unauthorized",
  "error_description": "Authentication required"
}

403 Forbidden

When authentication succeeded but there is no permission for the requested operation:

{
  "error": "forbidden",
  "error_description": "You do not have permission to perform this operation"
}

Tenant Context

API requests are executed in the tenant context associated with the authentication token. Cross-tenant data access is strictly restricted.

Multi-tenant Management

Users with system_admin or distributor_admin roles can manage multiple tenants. In this case, specify the tenant in the request header:

curl -X GET "https://{domain}/api/admin/users" \
  -H "Authorization: Bearer {admin-api-token}" \
  -H "X-Tenant-ID: {target-tenant-id}"

Best Practices

Principle of Least Privilege

Grant only the minimum required permission scopes to tokens.

# Bad example: Grant all permissions
# Scopes: *

# Good example: Only required permissions
# Scopes: users:read, users:write

Token Rotation

We recommend rotating API tokens regularly:

Generate a new token
Switch the application to the new token
Revoke the old token

Audit Log Review

Regularly review API token usage. If suspicious activity is detected, revoke the token immediately.