API
Token lifecycle
Validity, revocation and rotation of each credential, generated from the matrix.
Generated from the credential matrix · version 1 · sha 9d2b630103a5. Do not edit by hand: the source is src/credential-matrix.ts in the engine.
| Validity | Revocation | Rotation |
|---|
No expiry when created in the app. Signup: 30 days until the claim, which removes the expiry. OAuth: up to the consenter's validity or VALORBRAIN_OAUTH_TOKEN_MAX_TTL_DAYS. EMA: the issuer's token_ttl_seconds (default 900 s). | DELETE /api/v1/mcp/tokens/:id, the Revoke button in the app or POST /oauth/revoke; revoking the parent drops its OAuth children. | Create a new token, swap it in the client and revoke the old one. OAuth issues no refresh token: the client runs the consent again. |
| Validity | Revocation | Rotation |
|---|
| 30 days from signup unless someone claims the workspace; after the claim it does not expire. | Goes with the workspace (tenant deletion or a billing_status other than active), taking the OAuth tokens approved with it. | The key does not rotate; it reissues the signup vbm_ (POST /api/v1/agents/mcp-token: read write, toolset agent, same validity, the previous one revoked). Use the vbm_ day to day; after the claim, the claimer's personal token serves every agent of that person, each naming itself through the contract headers. |
| Validity | Revocation | Rotation |
|---|
api_tokens.expires_at when set; no expiry otherwise. | api_tokens.is_active = false (CLI tokens panel or member offboarding); the OAuth tokens approved with it go too. | Issue a new key through the same issuer and deactivate the old one. |
| Validity | Revocation | Rotation |
|---|
| The key's expiry when set; no expiry otherwise. | Delete the key in Settings → API keys. | Create a new key, swap it in the external system and delete the old one. |
| Validity | Revocation | Rotation |
|---|
| The app session's validity; not an integration contract. | Logout or member removal. | Sign in again. |
Short-lived values a flow hands out on the way to a credential. They are not credentials and authenticate no route.
| Credential | Issued by | Validity | Use |
|---|
| Claim code (OTP) | POST /api/v1/agents/claim | 10 minutes, up to 5 attempts | POST /api/v1/agents/claim/verify with the workspace's vb_agent_ |
| OAuth authorization code | GET /oauth/authorize → consentimento | Single use, minutes | POST /oauth/token with the PKCE code_verifier |
| OAuth client (DCR) | POST /oauth/register | Until removed; public client, no secret | client_id on /oauth/authorize and /oauth/token |
| Device code | POST https://valorbrain.valor.digital/api/v1/cli/device/code | Minutes, until a person approves it | Polled at POST /api/v1/cli/device/token; delivers the token once |
