Admin API

Everything you can manage in ScaiKey is exposed at /api/v1/admin/.... Authentication is Bearer JWT; the token must carry an admin role (super_admin, partner_admin, tenant_admin) or be a platform client_credentials token with admin:read and/or admin:write scope.

Authentication#

1

Authorization: Bearer <jwt>

For interactive admins, this is a user JWT obtained via the admin UI's login flow. For automated integrations, it's a client_credentials token from a GLOBAL SERVICE app whose allowed_scopes includes admin:read (read endpoints) or admin:write (write endpoints).

If you get 403 Platform token requires admin:read or admin:write scope, your service token's scopes are missing those entries — fix it at the application's allowed_scopes, not at the token request. See Troubleshooting → Platform token 403.

Resources#

Every resource follows the standard REST shape: GET / (list, paginated), POST / (create), GET /{id} (read), PATCH /{id} (partial update), DELETE /{id} (soft delete).

Partners#

1
2
3
4
5

GET    /api/v1/admin/partners
POST   /api/v1/admin/partners
GET    /api/v1/admin/partners/{id}
PATCH  /api/v1/admin/partners/{id}
DELETE /api/v1/admin/partners/{id}

Partner IDs are prefixed prt_. Fields include name, slug, status, contact_email, and three resource limit columns (max_tenants, max_users_per_tenant, max_applications_per_tenant). Limits are top-level integer fields, not a nested JSON blob.

super_admin only.

Tenants#

1
2
3
4
5

GET    /api/v1/admin/tenants
POST   /api/v1/admin/tenants
GET    /api/v1/admin/tenants/{id}
PATCH  /api/v1/admin/tenants/{id}
DELETE /api/v1/admin/tenants/{id}

Tenant IDs are prefixed tnt_. PATCH accepts name, slug, status, contact_email, partner_id (cross-partner transfer), settings (JSON), branding (JSON).

super_admin writes; partner_admin and tenant_admin read within their scope.

Users#

1
2
3
4
5
6
7

GET    /api/v1/admin/users
POST   /api/v1/admin/users
GET    /api/v1/admin/users/{id}
PATCH  /api/v1/admin/users/{id}
DELETE /api/v1/admin/users/{id}
POST   /api/v1/admin/users/{id}/reset-password
POST   /api/v1/admin/users/{id}/mfa/disable

User IDs prefixed usr_. Custom attributes (AD-compatible) live in custom_attributes JSON. PATCH never carries the password — use reset-password for that.

Groups#

1
2
3
4
5
6
7
8
9

GET    /api/v1/admin/groups
POST   /api/v1/admin/groups
GET    /api/v1/admin/groups/{id}
PATCH  /api/v1/admin/groups/{id}
DELETE /api/v1/admin/groups/{id}
POST   /api/v1/admin/groups/{id}/members
DELETE /api/v1/admin/groups/{id}/members/{user_id}
POST   /api/v1/admin/groups/{id}/nested
DELETE /api/v1/admin/groups/{id}/nested/{child_group_id}

Group IDs prefixed grp_. Nesting is fully supported — a group can contain other groups recursively.

Applications#

1
2
3
4
5

GET    /api/v1/admin/applications
POST   /api/v1/admin/applications
GET    /api/v1/admin/applications/{id}
PATCH  /api/v1/admin/applications/{id}
DELETE /api/v1/admin/applications/{id}

App IDs prefixed app_. The most-edited fields are allowed_scopes (list of permitted scopes), redirect_uris, allowed_origins, token_lifetime, and token_exchange_allowed. See Concepts → Applications for the full field set.

Identity providers#

1
2
3
4

GET    /api/v1/admin/identity-providers
POST   /api/v1/admin/identity-providers
PATCH  /api/v1/admin/identity-providers/{id}
DELETE /api/v1/admin/identity-providers/{id}

OIDC and SAML IdPs for federation. ID prefix idp_.

MCP agents#

1
2
3
4
5

GET    /api/v1/admin/agents
POST   /api/v1/admin/agents
GET    /api/v1/admin/agents/{id}
PATCH  /api/v1/admin/agents/{id}
DELETE /api/v1/admin/agents/{id}

AI agent identities for the MCP integration. ID prefix agt_. Carries allowed_tools and allowed_scopes lists, plus an optional rate_limit_rpm.

Sessions#

1
2
3

GET    /api/v1/admin/sessions
GET    /api/v1/admin/sessions/{id}
POST   /api/v1/admin/sessions/{id}/revoke

Active SSO sessions across the platform. Revoking terminates the session immediately and clears the SSO cookie on next browser hit.

Audit log#

1
2

GET    /api/v1/admin/audit
GET    /api/v1/admin/audit/{id}

Read-only. Every admin write and every authentication event is recorded with actor, action, resource, result, and IP/user-agent metadata.

Dashboard#

1
2

GET    /api/v1/admin/dashboard/stats
GET    /api/v1/admin/dashboard/activity

Aggregate counters and recent activity feed — what the admin UI's home page renders.

Hierarchical access rules#

Most read endpoints accept admins of any tier (filtered to what they're allowed to see). Most write endpoints check a hierarchical access rule:

• super_admin — everything.
• partner_admin — partners and tenants under their own partner, and any resource within those tenants.
• tenant_admin — only their own tenant's resources.

Cross-tier writes (e.g. tenant_admin trying to PATCH a GLOBAL app) get 403 Access denied.

Pagination#

List endpoints accept ?page=N and ?per_page=M (default 20, max 100). Responses include pagination: { page, per_page, total, total_pages }.

Pydantic schemas#

If you're generating types, the live OpenAPI spec is at $SCAIKEY/openapi.json on non-production builds. The Pydantic models behind it live in backend/src/scaikey/schemas/ in the open-source backend repo.