Users and Access Reference

User management, API keys, groups, custom roles, and group-to-role mappings. For concepts, see Roles and Permissions.

Users#

GET /v1/users#

List users in the caller's tenant. Requires users:manage.

Query params: limit, cursor, status (active / suspended).

GET /v1/users/{user_id}#

Get a user's profile. Requires users:manage or the caller being the user themselves.

PUT /v1/users/{user_id}/roles#

Update a user's built-in roles.

json
{"roles": ["tenant_user", "tenant_viewer"], "custom_role_ids": []}

Requires users:manage.

GET /v1/users/{user_id}/module-permissions#

List module permissions granted directly to the user (not through roles).

PUT /v1/users/{user_id}/module-permissions#

Grant or revoke direct module permissions.

json
{"permissions": ["scaibot:bots:create", "scaimatrix:ingest"]}

Replaces the entire set. Requires users:manage.

DELETE /v1/users/{user_id}#

Soft-delete a user. Their API keys are revoked, their active sessions are killed. Requires users:manage.

GET /v1/me#

Get the current authenticated user's profile. Equivalent to GET /v1/auth/me.

API keys#

GET /v1/api-keys#

List API keys owned by the caller.

POST /v1/api-keys#

Create a new API key.

bash
curl -X POST https://scaigrid.scailabs.ai/v1/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "production-integration",
    "expires_at": "2027-04-22T00:00:00Z",
    "assigned_user_id": null
  }'

Response (shows the full key exactly once):

json
{
  "data": {
    "id": "apikey_xyz",
    "name": "production-integration",
    "key": "sgk_full_key_here_shown_once",
    "prefix": "sgk_",
    "scopes": [...],
    "expires_at": "2027-04-22T00:00:00Z",
    "created_at": "2026-04-22T..."
  }
}

Subsequent GETs return metadata only — the database stores a SHA-256 hash, not the key.

DELETE /v1/api-keys/{key_id}#

Revoke an API key. Immediate effect. Requires api_keys:manage.

Groups#

Groups come from ScaiKey — you don't create them in ScaiGrid directly. ScaiGrid syncs them and lets you configure how they map to roles.

GET /v1/groups#

List groups synced from ScaiKey into the tenant.

GET /v1/groups/{group_id}#

Get a group's members and metadata.

Role mappings#

Role mappings tell ScaiGrid which ScaiKey group corresponds to which ScaiGrid role. When a user authenticates, their ScaiKey group memberships resolve to roles via these mappings.

GET /v1/role-mappings#

List all mappings for the tenant.

POST /v1/role-mappings#

Create a mapping.

json
{
  "scaikey_group": "acme-engineers",
  "scaigrid_role": "tenant_user",
  "tenant_id": "tenant_acme",
  "auto_revoke": true
}

auto_revoke: true means a user removed from the ScaiKey group loses the role on next authentication.

PUT /v1/role-mappings/{mapping_id}#

Update a mapping.

DELETE /v1/role-mappings/{mapping_id}#

Remove a mapping. Users who had the role through this mapping lose it on next authentication.

Custom roles#

GET /v1/custom-roles#

List custom roles defined in the tenant.

POST /v1/custom-roles#

Create a custom role.

json
{
  "name": "Analytics Team",
  "slug": "analytics",
  "description": "Read-only access to usage and export",
  "core_permissions": ["accounting:view_tenant", "models:list"],
  "module_permissions": []
}

GET /v1/custom-roles/available-permissions#

List all permissions available to assemble into custom roles. Both core permissions and module permissions from enabled modules.

GET /v1/custom-roles/{role_id}#

Get a custom role's definition.

PUT /v1/custom-roles/{role_id}#

Update a custom role's permission set, name, or description.

DELETE /v1/custom-roles/{role_id}#

Delete a custom role. Users who had it lose its permissions.