Credentials API

The Credentials API provides a unified interface for managing all types of credentials in ButtrBase: API keys, service account tokens, SCIM tokens, and webhook signing secrets.

API Keys

POST /api/admin/organizations/:org_uuid/api-keys

Generates a new organization API key.

Input: ~~~json { "name": "Production API Key", "scopes": ["read:users", "write:features"], "expires_in_days": 365 } ~~~

Output: ~~~json { "key_id": "key-uuid-123", "api_key": "bb_live_...", "name": "Production API Key", "scopes": ["read:users", "write:features"], "expires_at": "2025-07-11T00:00:00Z" } ~~~

Note: The api_key value is only returned once. Store it securely.

GET /api/admin/organizations/:org_uuid/api-keys

Lists all API keys for the organization (without key values).

DELETE /api/admin/organizations/:org_uuid/api-keys/:key_id

Revokes an API key immediately.

SCIM Tokens

POST /api/admin/organizations/:org_uuid/scim-tokens

Generates a new SCIM provisioning token.

DELETE /api/admin/organizations/:org_uuid/scim-tokens/:token_id

Revokes a SCIM token.

Webhook Signing Secrets

POST /api/webhooks/:webhook_id/rotate-secret

Rotates the signing secret for a webhook endpoint. The old secret remains valid for 24 hours.

Output: ~~~json { "new_secret": "whsec_...", "old_secret_expires_at": "2024-07-12T10:00:00Z" } ~~~

Error Reference

| Status | Code | Meaning | |--------|------|---------| | 400 | validation_error | Request body failed validation | | 401 | unauthorized | Missing or invalid Authorization header | | 403 | forbidden | Insufficient permissions | | 404 | not_found | Resource does not exist | | 409 | conflict | Resource already exists or constraint violated | | 422 | unprocessable | Semantic validation failure | | 429 | rate_limited | Request rate exceeded | | 500 | internal_error | Unexpected server error |