Identity Management API

The Management API is rooted at /identity/admin on the environment’s control issuer. It accepts a bearer token issued by that control tenant for audience identity-admin-api.

Authorization

For terminal use, identityctl login opens an operator session and identityctl token refreshes that session before emitting an access token. Register a separate confidential administration client for unattended automation and grant only the scopes it needs.

Collection routes use the shared pagination contract.

Overview

GET /overview returns environment-wide totals.

Response — 200 OK

{
  "tenants": 12,
  "clients": 37,
  "resources": 18,
  "activeFederations": 4
}

Tenants

Creation accepts:

{
  "slug": "acme",
  "registrationMode": "CONTROLLED"
}

registrationMode is CONTROLLED or SELF_SERVICE. Identity assigns the tenant ID and managed issuer during creation. A later update accepts slug, issuer and registrationMode, subject to the lock fields returned for the tenant.

Tenant response

{
  "id": "f351511c-11e4-408f-b069-1c58baf673af",
  "slug": "acme",
  "issuer": "https://f351511c-11e4-408f-b069-1c58baf673af.auth.example.com",
  "status": "ACTIVE",
  "registrationMode": "CONTROLLED",
  "clientCount": 2,
  "resourceCount": 1,
  "createdAt": "2026-10-13T08:42:11.384Z",
  "managedIssuer": "https://f351511c-11e4-408f-b069-1c58baf673af.auth.example.com",
  "configurationManaged": false,
  "slugLocked": false,
  "issuerLocked": false
}

Users

User reads and writes require identity.admin.users.manage.

CONTROL_ISSUER='https://auth.identity.lookandtry.com'
TENANT_ID='00000000-0000-0000-0000-000000000000'
curl --fail --silent --show-error \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  "$CONTROL_ISSUER/identity/admin/tenants/$TENANT_ID/users?page=0&size=25"

Create accepts email and optional emailVerified, which defaults to false. Update replaces email, emailVerified and status, where status is ACTIVE or DISABLED.

User response

{
  "id": "8b6e839c-114b-4242-ac95-7158a39fce39",
  "subject": "usr_01JY7N8SV4B30TQGB8Y3YH5J9M",
  "email": "ada@example.com",
  "emailVerified": true,
  "status": "ACTIVE",
  "createdAt": "2026-10-13T08:42:11.384Z"
}

Use subject, together with the tenant issuer, when another system needs to bind its account to this Identity user. id addresses the management resource and is used in the user route.

Resources

Creation accepts uri, audience and scopes.

{
  "uri": "https://api.acme.example",
  "audience": "acme-api",
  "status": "ACTIVE",
  "scopes": ["orders.read", "orders.write"]
}

The resource URI is used by authorization requests. The audience is the value a receiving API expects in aud.

OAuth clients

Create and update accept:

{
  "clientId": "acme-web",
  "displayName": "Acme web",
  "applicationType": "WEB",
  "tokenEndpointAuthMethod": "CLIENT_SECRET_BASIC",
  "consentPolicy": "EXPLICIT",
  "redirectUris": ["https://app.acme.example/callback"],
  "scopes": ["openid", "email", "offline_access", "orders.read"],
  "defaultResource": "https://api.acme.example",
  "nativeAuthenticationEnabled": false
}

applicationType is WEB or NATIVE. tokenEndpointAuthMethod is CLIENT_SECRET_BASIC or NONE. consentPolicy is EXPLICIT or PRE_AUTHORIZED.

Issuance response

{
  "clientId": "acme-web",
  "clientSecret": "cs_aF9m4vQ3..."
}

clientSecret is null for a public client. When a secret is returned, capture it immediately; it is not available from list responses.

Client metadata in list responses

{
  "clientId": "acme-web",
  "displayName": "Acme web",
  "applicationType": "WEB",
  "tokenEndpointAuthMethod": "CLIENT_SECRET_BASIC",
  "consentPolicy": "EXPLICIT",
  "status": "ACTIVE",
  "redirectUris": ["https://app.acme.example/callback"],
  "scopes": ["email", "offline_access", "openid", "orders.read"],
  "defaultResource": "https://api.acme.example",
  "nativeAuthenticationEnabled": false,
  "createdAt": "2026-10-13T08:47:20.118Z",
  "configurationManaged": false
}

Resource-server credentials

Issue a credential for a previously registered resourceUri:

{
  "resourceUri": "https://api.acme.example"
}

Issuance response

{
  "credentialId": "rsc_4jWc2L...",
  "credentialSecret": "rss_L7e9Qx..."
}

Store credentialSecret immediately. List responses expose credentialId, resourceUri, status and createdAt, never the secret.

Signing keys

A staged key response is:

{
  "keyId": "key-2026-10"
}

List entries contain keyId, state, createdAt, activatedAt and retiredAt. State is STAGED, ACTIVE, RETIRING, RETIRED or REVOKED. Activate before using a staged key to sign new tokens. Keep old public keys available long enough to validate tokens issued before rotation.

Federations and audit events

Federation creation accepts:

{
  "sourceTenantId": "f351511c-11e4-408f-b069-1c58baf673af",
  "targetTenantId": "3b85c18a-b2a4-4f0d-8b9d-624bd436ed11"
}

A federation entry returns both tenant IDs, both issuers, status and createdAt. An audit event returns id, actorSubject, actorClientId, action, targetType, targetId, details and createdAt.

Bulk user imports and exports

Imports accept at most 500 records per request with schemaVersion: 1. The tuple (source, externalId) identifies one source-system account. idempotencyKey makes an exact retry return the same logical job and rejects a different payload using the same key. mode is CREATE_ONLY or VALIDATE_ONLY.

CONTROL_ISSUER='https://auth.identity.lookandtry.com'
TENANT_ID='00000000-0000-0000-0000-000000000000'
curl --fail --silent --show-error \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{
    "schemaVersion": 1,
    "source": "customer-backend",
    "mode": "CREATE_ONLY",
    "idempotencyKey": "migration-2026-10-13-part-1",
    "records": [{
      "externalId": "42",
      "email": "user@example.com",
      "emailVerified": true,
      "active": true
    }]
  }' \
  "$CONTROL_ISSUER/identity/admin/tenants/$TENANT_ID/user-imports"

Accepted job — 202 Accepted

{
  "id": "e8b7c344-c409-4f7a-99c4-f21142cfaf18",
  "tenantId": "f351511c-11e4-408f-b069-1c58baf673af",
  "kind": "IMPORT",
  "status": "QUEUED",
  "source": "legacy-crm",
  "mode": "CREATE_ONLY",
  "totalItems": 2,
  "processedItems": 0,
  "succeededItems": 0,
  "failedItems": 0,
  "createdAt": "2026-10-13T09:00:00Z",
  "startedAt": null,
  "completedAt": null,
  "lastFailure": null
}

Poll the job until status is SUCCEEDED, COMPLETED_WITH_ERRORS, FAILED or CANCELLED. QUEUED and RUNNING are non-terminal.

Import result record

{
  "position": 0,
  "externalId": "legacy-42",
  "email": "ada@example.com",
  "status": "SUCCEEDED",
  "subject": "usr_01JY7N8SV4B30TQGB8Y3YH5J9M",
  "errorCode": null,
  "processedAt": "2026-10-13T09:00:02.118Z"
}

Store the externalId to subject mapping for any source system that must bind product accounts after migration. Failed records have status: "FAILED", a null subject and a machine-readable errorCode.

Export record and NDJSON

{
  "position": 0,
  "subject": "usr_01JY7N8SV4B30TQGB8Y3YH5J9M",
  "email": "ada@example.com",
  "emailVerified": true,
  "status": "ACTIVE",
  "createdAt": "2024-02-17T12:21:44Z"
}

The download response contains one JSON object per line with the same export-record shape. Process it as a stream; do not load the entire file into memory.

An import record may carry a bcrypt password hash, a TOTP factor and upstream identities in addition to email state. See account migrations for the complete source export, import verification and product-binding workflow.

Errors

Management errors use {"error":"code"}.