Identity

Endpoint reference for the identity cache (partners, tenants, users, groups) mirrored from ScaiKey.

Base path: /v1/identity/

Identity cache#

ScaiVault keeps a local cache of identity data from ScaiKey for fast policy evaluation. The cache is updated in real time via webhooks from ScaiKey; you can also trigger manual syncs.

GET /v1/identity/partners#

List cached partners.

Query: status, page, page_size.

Response:

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

{
  "partners": [
    {
      "id": "ptn_abc",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "region": "us-east-1",
      "status": "ACTIVE",
      "last_synced_at": "..."
    }
  ],
  "total": 10
}

Scope: identity:read.

GET /v1/identity/tenants#

List cached tenants.

Query: partner_id, status, page, page_size.

Scope: identity:read.

GET /v1/identity/tenants/{tenant_id}/users#

List users in a tenant.

Query: status, page, page_size, q (email/name search).

Response:

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

{
  "users": [
    {
      "id": "usr_abc",
      "tenant_id": "tnt_xyz",
      "email": "alice@acme.example",
      "display_name": "Alice Smith",
      "status": "ACTIVE",
      "mfa_enabled": true,
      "groups": ["grp_sre", "grp_oncall"],
      "roles": ["tenant_admin"],
      "last_synced_at": "..."
    }
  ],
  "total": 150
}

Scope: identity:read.

GET /v1/identity/tenants/{tenant_id}/groups#

List groups.

Scope: identity:read.

GET /v1/identity/groups/{group_id}/members#

List members.

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "members": [
    {
      "user_id": "usr_abc",
      "email": "alice@acme.example",
      "membership_type": "DIRECT",
      "added_at": "..."
    }
  ],
  "total": 12
}

Scope: identity:read.

GET /v1/identity/resolve/{identity_type}/{identity_id}#

Resolve an identity from the cache, with group memberships.

Response:

1
2
3
4
5
6
7
8
9

{
  "id": "usr_abc",
  "type": "user",
  "email": "alice@acme.example",
  "tenant_id": "tnt_xyz",
  "status": "ACTIVE",
  "groups": ["grp_sre", "grp_oncall"],
  "roles": ["tenant_admin"]
}

Returns 404 identity_not_found if unknown.

Scope: identity:read.

POST /v1/identity/sync#

Trigger manual sync from ScaiKey.

Query: partner_id, tenant_id (optional; omit for full sync).

Response 202 Accepted: sync_id, status, started_at.

Scope: identity:admin.

GET /v1/identity/sync/history#

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

{
  "syncs": [
    {
      "id": 42,
      "sync_type": "FULL",
      "status": "COMPLETED",
      "partners_synced": 5,
      "tenants_synced": 25,
      "users_synced": 1500,
      "groups_synced": 200,
      "duration_ms": 45000,
      "started_at": "...",
      "completed_at": "..."
    }
  ]
}

Scope: identity:read.

GET /v1/identity/roles#

Available admin roles for assignment.

Scope: authenticated.

GET /v1/identity/users/{user_id}/roles#

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

Body: {"roles": ["tenant_admin"]}.

Auth rules:

• Only super_admin or partner_admin can modify roles.
• Only super_admin can grant super_admin.
• No self-elevation.

POST /v1/identity/webhooks/scaikey#

Webhook receiver for ScaiKey events. ScaiKey itself POSTs here; not called by user code.

Verifies X-ScaiKey-Signature and applies the event to the cache.

Related#

• Multi-tenancy
• Authentication