Token Vault Endpoints

Store, retrieve, and manage third-party OAuth tokens on behalf of agents and users.

Store Token

POST /api/v1/vault/tokens

Headers

• Authorization: Bearer <apiKey>
• X-Bulwark-Tenant: <tenant-id>

Body

{
  "provider": "github",
  "userId": "usr_01j...",
  "accessToken": "gho_...",
  "refreshToken": "ghr_...",
  "expiresAt": "2026-04-18T00:00:00Z",
  "scopes": ["repo", "read:user"],
  "metadata": {
    "githubUsername": "jdoe"
  }
}

Response 201

{
  "data": {
    "tokenId": "vt_01j...",
    "provider": "github",
    "userId": "usr_01j...",
    "scopes": ["repo", "read:user"],
    "expiresAt": "2026-04-18T00:00:00Z",
    "createdAt": "2026-03-18T00:00:00Z"
  }
}

Token values are encrypted at rest. The plaintext is never stored.

Get Token

GET /api/v1/vault/tokens/{tokenId}

Returns metadata only — not the token value.

Response 200

{
  "data": {
    "tokenId": "vt_01j...",
    "provider": "github",
    "userId": "usr_01j...",
    "scopes": ["repo", "read:user"],
    "expiresAt": "2026-04-18T00:00:00Z",
    "status": "valid"
  }
}

List Tokens for User

GET /api/v1/vault/tokens?userId={userId}

Response 200

{
  "data": [
    {
      "tokenId": "vt_01j...",
      "provider": "github",
      "scopes": ["repo", "read:user"],
      "expiresAt": "2026-04-18T00:00:00Z",
      "status": "valid"
    },
    {
      "tokenId": "vt_02j...",
      "provider": "slack",
      "scopes": ["chat:write"],
      "expiresAt": "2026-05-01T00:00:00Z",
      "status": "valid"
    }
  ]
}

Revoke Token

DELETE /api/v1/vault/tokens/{tokenId}

Response 200

{
  "data": {
    "tokenId": "vt_01j...",
    "status": "revoked",
    "revokedAt": "2026-03-18T13:00:00Z"
  }
}

Exchange Token (for proxy use)

This endpoint is used internally by the credential proxy. Direct use requires the vault:exchange scope.

POST /api/v1/vault/tokens/{tokenId}/exchange

Returns a short-lived, single-use credential for a proxied API call.

Response 200

{
  "data": {
    "credential": "...",
    "expiresAt": "2026-03-18T13:01:00Z"
  }
}