API Key Endpoints

Manage tenant API keys for server-to-server authentication.

Create API Key

POST /api/v1/api-keys

Headers

• Authorization: Bearer <adminToken>
• X-Bulwark-Tenant: <tenant-id>
• X-Bulwark-App-Id: <app-id> — Optional. Scopes the API key to a specific application.

Body

{
  "name": "mimir-runtime",
  "scopes": ["fga:read", "fga:write"],
  "expires_at": "2027-01-01T00:00:00Z"
}

scopes is validated against the server's scope registry and is required — at least one scope must be supplied. Unknown scope strings return 400 Bad Request with the offending scope(s) named in the error.

Response 201

{
  "id": "key_01j...",
  "name": "mimir-runtime",
  "key": "bwk_live_...",
  "key_prefix": "bwk_live_abcd1234",
  "environment": "live",
  "scopes": ["fga:read", "fga:write"],
  "created_at": "2026-03-18T00:00:00Z"
}

Important: The key value is only returned once. Store it immediately.

List API Keys

GET /api/v1/api-keys

Response 200

{
  "api_keys": [
    {
      "id": "key_01j...",
      "name": "mimir-runtime",
      "key_prefix": "bwk_live_abcd1234",
      "environment": "live",
      "scopes": ["fga:read", "fga:write"],
      "last_used_at": "2026-03-18T12:00:00Z",
      "expires_at": "2027-01-01T00:00:00Z",
      "revoked_at": null,
      "created_at": "2026-03-18T00:00:00Z"
    }
  ]
}

Key values are never returned after creation.

List Available Scopes

GET /api/v1/api-keys/scopes

Returns the registry of valid scope strings, grouped for display. Use this to populate scope pickers in tooling so callers cannot fat-finger a scope name into a key that silently fails.

Response 200

{
  "scopes": [
    {
      "name": "fga:read",
      "group": "FGA",
      "description": "Read authorization tuples and run check / filter / list-objects queries."
    },
    {
      "name": "fga:write",
      "group": "FGA",
      "description": "Write and delete authorization tuples. Implies fga:read for evaluation."
    }
  ]
}

Revoke API Key

DELETE /api/v1/api-keys/{id}

Immediately invalidates the key.

Response 200

{
  "status": "revoked"
}

Available Scopes

The set of scopes the server will accept is the source of truth at GET /api/v1/api-keys/scopes. Today:

| Scope | Group | Description | | ------------- | ----- | ------------------------------------------------------------------------ | | fga:read | FGA | Read authorization tuples and run check / filter / list-objects queries. | | fga:write | FGA | Write and delete authorization tuples. Implies fga:read for evaluation. | | users:read | Users | List and fetch users in the workspace (admin read access). | | users:write | Users | Create, update, and delete users. Required for programmatic user provisioning (e.g. invitation-accept flows). | | vault:read | Vault | List configured services in the vault registry. Does NOT expose stored secret values — those are vended through credential.Service.Vend with policy enforcement. | | vault:write | Vault | Store encrypted secrets and upsert service configs. Required for programmatic vault provisioning (CI seeding, deployment scripts). | | sessions:read | Sessions | List a user's active login sessions (signed-in devices) including device fingerprint, IP, and last-seen timestamp. Powers tenant-portal "active sessions" UIs. | | sessions:write | Sessions | Revoke individual user login sessions or sign a user out of all devices. Required for tenant-portal "sign out everywhere" actions. |

Other Bulwark surfaces (agents, audit, webhooks) do not yet enforce scopes — those endpoints currently authenticate via JWT only and ignore key scopes. Scope-based auth rolls out incrementally; this page and the scopes endpoint reflect what the server enforces today.