Veto/docs

API Keys

Create, list, update, revoke, and delete API keys — the credentials that authenticate SDK and API requests.

API keys authenticate requests from the SDK, CLI, and direct API calls. Each key is scoped to an organization and project. The full key value is only returned once at creation time.

All endpoints require authentication via Bearer JWT with X-Organization-Id header, or an existing API key (X-Veto-API-Key).

GET /v1/api-keys

List all API keys for the authenticated organization.

Headers

HeaderRequiredDescription
X-Veto-API-Key or AuthorizationYesAPI key or Bearer JWT

Response

{
  "data": [
    {
      "id": "k57a8b2c3d4e5f6a7",
      "name": "Production API Key",
      "keyPrefix": "veto_abc1...",
      "isRevoked": false,
      "lastUsedAt": "2025-01-20T14:30:00Z",
      "createdAt": "2025-01-15T10:00:00Z"
    }
  ]
}

Example

curl https://api.veto.so/v1/api-keys \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "X-Organization-Id: org_abc123"

POST /v1/api-keys

Create a new API key. The full key is returned only in this response. Store it securely.

Headers

HeaderRequiredDescription
X-Veto-API-Key or AuthorizationYesAPI key or Bearer JWT
Content-TypeYesapplication/json

Body

{
  "name": "Production API Key",
  "projectId": "proj_abc123"
}
FieldTypeRequiredDescription
namestringYesDisplay name (1-100 chars)
projectIdstringYesProject to scope this key to

Response (201)

{
  "id": "k57a8b2c3d4e5f6a7",
  "name": "Production API Key",
  "key": "veto_abc123def456ghi789...",
  "keyPrefix": "veto_abc1...",
  "createdAt": "2025-01-20T14:30:00Z",
  "warning": "This is the only time the full API key will be shown. Please save it securely."
}
FieldTypeDescription
idstringAPI key record ID
namestringDisplay name
keystringFull API key value (only shown once)
keyPrefixstringTruncated prefix for identification
createdAtstringISO 8601 creation timestamp
warningstringReminder to save the key

Example

curl -X POST https://api.veto.so/v1/api-keys \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "X-Organization-Id: org_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Staging API Key",
    "projectId": "proj_abc123"
  }'

GET /v1/api-keys/:id

Get a single API key by ID. The full key value is never returned after creation.

Headers

HeaderRequiredDescription
X-Veto-API-Key or AuthorizationYesAPI key or Bearer JWT

Path parameters

ParameterTypeDescription
idstringAPI key record ID

Response

{
  "id": "k57a8b2c3d4e5f6a7",
  "name": "Production API Key",
  "keyPrefix": "veto_abc1...",
  "isRevoked": false,
  "lastUsedAt": "2025-01-20T14:30:00Z",
  "createdAt": "2025-01-15T10:00:00Z"
}

Errors

StatusCodeDescription
404not_foundAPI key does not exist or belongs to a different org

Example

curl https://api.veto.so/v1/api-keys/k57a8b2c3d4e5f6a7 \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "X-Organization-Id: org_abc123"

PATCH /v1/api-keys/:id

Update the display name of an API key.

Headers

HeaderRequiredDescription
X-Veto-API-Key or AuthorizationYesAPI key or Bearer JWT
Content-TypeYesapplication/json

Path parameters

ParameterTypeDescription
idstringAPI key record ID

Body

{
  "name": "Renamed API Key"
}
FieldTypeRequiredDescription
namestringYesNew display name (1-100 chars)

Response

{
  "id": "k57a8b2c3d4e5f6a7",
  "name": "Renamed API Key",
  "keyPrefix": "veto_abc1...",
  "isRevoked": false,
  "lastUsedAt": "2025-01-20T14:30:00Z",
  "createdAt": "2025-01-15T10:00:00Z"
}

Errors

StatusCodeDescription
404not_foundAPI key does not exist or belongs to a different org

Example

curl -X PATCH https://api.veto.so/v1/api-keys/k57a8b2c3d4e5f6a7 \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "X-Organization-Id: org_abc123" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Renamed API Key" }'

POST /v1/api-keys/:id/revoke

Revoke an API key. Revoked keys immediately stop authenticating requests. The key record is preserved for audit purposes.

Headers

HeaderRequiredDescription
X-Veto-API-Key or AuthorizationYesAPI key or Bearer JWT

Path parameters

ParameterTypeDescription
idstringAPI key record ID

Response

{
  "success": true,
  "message": "API key has been revoked",
  "id": "k57a8b2c3d4e5f6a7",
  "isRevoked": true
}

Errors

StatusCodeDescription
404not_foundAPI key does not exist or belongs to a different org

Example

curl -X POST https://api.veto.so/v1/api-keys/k57a8b2c3d4e5f6a7/revoke \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "X-Organization-Id: org_abc123"

DELETE /v1/api-keys/:id

Permanently delete an API key record. Unlike revocation, this removes the key from the database entirely.

Headers

HeaderRequiredDescription
X-Veto-API-Key or AuthorizationYesAPI key or Bearer JWT

Path parameters

ParameterTypeDescription
idstringAPI key record ID

Response

{
  "success": true
}

Errors

StatusCodeDescription
404not_foundAPI key does not exist or belongs to a different org

Example

curl -X DELETE https://api.veto.so/v1/api-keys/k57a8b2c3d4e5f6a7 \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "X-Organization-Id: org_abc123"

API key response fields

FieldTypeDescription
idstringRecord ID
namestringDisplay name
keyPrefixstringTruncated key prefix (e.g. veto_abc1...)
isRevokedbooleanWhether the key has been revoked
lastUsedAtstring?ISO 8601 timestamp of last use
createdAtstringISO 8601 creation timestamp

Approvals API

Endpoints for human-in-the-loop approval workflows — list, create, poll, and resolve approvals.

Organizations API

CRUD endpoints for organizations — the top-level scope for projects, policies, and API keys.

On this page

GET /v1/api-keysHeadersResponseExamplePOST /v1/api-keysHeadersBodyResponse (201)ExampleGET /v1/api-keys/:idHeadersPath parametersResponseErrorsExamplePATCH /v1/api-keys/:idHeadersPath parametersBodyResponseErrorsExamplePOST /v1/api-keys/:id/revokeHeadersPath parametersResponseErrorsExampleDELETE /v1/api-keys/:idHeadersPath parametersResponseErrorsExampleAPI key response fields