Users, Groups, and Roles Reference

Endpoints for managing users, groups, and role assignments. For the conceptual model, see Tenants and Users and Permissions and Access.

Identities (users, groups, tenants) are primarily owned by ScaiKey. These endpoints proxy to ScaiKey for writes and surface the local cache for reads.

Required permission: Most endpoints require tenant admin or platform admin.

Users#

Base path: /api/v1/admin/users/

GET /admin/users/#

List users in the current tenant.

Query parameters:

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{
  "data": [
    {
      "id": "u_abc123",
      "scaikey_user_id": "usr_...",
      "email": "user@example.com",
      "name": "User Name",
      "status": "active",
      "is_platform_admin": false,
      "is_tenant_admin": false,
      "created_at": "2026-04-01T10:00:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "page_size": 50
}

GET /admin/users/{user_id}#

Get a single user. Accepts either internal UUID or ScaiKey user ID.

POST /admin/users/#

Create a user (proxied to ScaiKey).

Request:

Response: Created user.

PATCH /admin/users/{user_id}#

Update user profile fields.

DELETE /admin/users/{user_id}#

Disable user in ScaiKey. Does not hard-delete — the user can be reactivated.

POST /admin/users/{user_id}/password#

Reset a user's password.

Request: {"password": "new-password"}

POST /admin/users/invite#

Send an invitation email for a new user.

POST /admin/users/{user_id}/resend-invite#

Resend an invitation email.

Groups#

Base path: /api/v1/admin/groups/

GET /admin/groups/#

List groups in the current tenant.

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "data": [
    {
      "id": "g_abc123",
      "name": "DNS Admins",
      "slug": "dns-admins",
      "description": "Tenant-level DNS administrators",
      "group_type": "SECURITY",
      "scope": "tenant",
      "member_count": 3,
      "created_at": "..."
    }
  ]
}

POST /admin/groups/#

Create a group.

Request:

GET /admin/groups/{group_id}#

Get a single group.

PATCH /admin/groups/{group_id}#

Update group metadata.

DELETE /admin/groups/{group_id}#

Delete a group. Members are unaffected (their membership is removed).

GET /admin/groups/{group_id}/members#

List group members.

Response:

1
2
3
4
5
6

{
  "data": [
    {"user_id": "u_abc", "email": "user@example.com", "joined_at": "..."}
  ],
  "total": 3
}

POST /admin/groups/{group_id}/members#

Add a user to a group.

Request: {"member_id": "u_abc123"}

DELETE /admin/groups/{group_id}/members/{member_id}#

Remove a user from a group.

Roles#

Base path: /api/v1/roles/

GET /roles/#

List roles available in the tenant.

Query parameters:

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "data": [
    {
      "id": "r_platform_admin",
      "name": "platform_admin",
      "description": "Full platform administration",
      "is_system": true,
      "permissions": {
        "domains": ["read", "create", "update", "delete"],
        "records": ["read", "create", "update", "delete"],
        "dnssec": ["read", "enable", "disable", "rotate"],
        "platform": ["config", "audit", "manage_tenants"]
      }
    }
  ]
}

GET /roles/{role_id}#

Get a single role.

POST /roles/#

Create a custom role (tenant admin only). Cannot grant permissions the creator doesn't have.

Request:

1
2
3
4
5
6
7
8

{
  "name": "record-bot",
  "description": "Automation role for record changes",
  "permissions": {
    "records": ["read", "create", "update", "delete"],
    "domains": ["read"]
  }
}

PATCH /roles/{role_id}#

Update a custom role (cannot modify system roles).

DELETE /roles/{role_id}#

Delete a custom role. Role assignments referencing it are removed.

GET /roles/users/{user_id}#

List a user's role assignments.

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "data": [
    {
      "id": "ur_abc",
      "user_id": "u_xyz",
      "role_id": "r_tenant_admin",
      "role_name": "tenant_admin",
      "scope": "tenant",
      "scope_resource_id": null,
      "expires_at": null,
      "granted_by": "u_admin",
      "granted_at": "..."
    }
  ]
}

POST /roles/users/{user_id}#

Assign a role to a user.

Request:

1
2
3
4
5
6

{
  "role_id": "r_domain_manager",
  "scope": "domain",
  "scope_resource_id": "d_zone_uuid",
  "expires_at": "2026-12-31T23:59:59Z"
}

Scopes: platform, tenant, domain. For domain scope, scope_resource_id is required.

DELETE /roles/users/{user_id}/{assignment_id}#

Remove a role assignment.

POST /roles/groups/{group_id}#

Assign a role to a group. Members inherit it.

Request: Same as user assignment.

DELETE /roles/groups/{group_id}/{assignment_id}#

Remove a group's role assignment.

GET /roles/users/{user_id}/permissions#

Get a user's resolved effective permissions.

Query parameters:

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "is_platform_admin": false,
  "is_tenant_admin": true,
  "roles": [
    {"role_name": "tenant_admin", "scope": "tenant", "scope_resource_id": null}
  ],
  "permissions": {
    "domains": ["read", "create", "update", "delete"],
    "records": ["read", "create", "update", "delete"],
    "dnssec": ["read", "enable", "disable", "rotate"]
  }
}

Error codes#

Related#

• Permissions and Access — how authorization resolves.
• Tenants and Users — identity model.
• Access Grants — per-domain delegation.