Credentials API

The Credentials API provides a unified admin interface for managing all platform credential types. Every credential — regardless of type — supports the same rotation, listing, and revocation operations.

For the admin guide covering concepts and operational procedures, see Credential Management. For developer integration, see Key Rotation Integration Guide.

---

Authentication

All endpoints require authentication via Bearer token with admin role:

Authorization: Bearer <admin-api-key>

---

Endpoints

Base path: /api/v1/admin/credentials

Method	Path	Description
GET	/api/v1/admin/credentials	List credentials with optional filters
POST	/api/v1/admin/credentials/{credential_id}/rotate	Rotate a credential’s secret
DELETE	/api/v1/admin/credentials/{credential_id}	Revoke a credential

---

List credentials

GET /api/v1/admin/credentials

Returns metadata for all credentials. Secrets and hashes are never included in responses.

Query parameters:

Parameter	Type	Required	Description
org_id	UUID	No	Filter by organization
type	string	No	Filter by credential type: oauth_client, api_key, scim_token, client_identity

Example:

# List all credentials
curl https://api.arbitex.ai/api/v1/admin/credentials \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# Filter by org and type
curl "https://api.arbitex.ai/api/v1/admin/credentials?org_id=019577a3-1111-2222-3333-444455556666&type=api_key" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Response (200 OK):

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "org_id": "019577a3-1111-2222-3333-444455556666",
    "type": "api_key",
    "owner_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "owner_type": "user",
    "name": "ci-pipeline-prod",
    "key_prefix": "arx_a1b2",
    "status": "active",
    "grace_period_seconds": 3600,
    "created_at": "2026-03-01T00:00:00Z",
    "rotated_at": "2026-04-01T12:00:00Z",
    "revoked_at": null
  }
]

Response schema (CredentialResponse[]):

Field	Type	Description
id	UUID	Credential identifier
org_id	UUID	Owning organization
type	string	One of: oauth_client, api_key, scim_token, client_identity
owner_id	UUID	UUID of the entity that owns this credential
owner_type	string	One of: user, oauth_client, scim_config, client_identity
name	string	Human-readable label
key_prefix	string	First 8 characters of the secret (for identification)
status	string	One of: active, revoked, expired
grace_period_seconds	integer	Duration the previous secret stays valid after rotation
created_at	datetime	When the credential was created
rotated_at	datetime | null	When the credential was last rotated
revoked_at	datetime | null	When the credential was revoked (if applicable)

Error responses:

Status	Condition
401 Unauthorized	Missing or invalid Bearer token
403 Forbidden	Caller does not have admin role
422 Unprocessable Entity	Invalid type filter value

---

Rotate credential

POST /api/v1/admin/credentials/{credential_id}/rotate

Generates a new secret for the credential. The current secret is demoted to previous and remains valid for the configured grace period. The new plaintext secret is returned once and is never retrievable again.

Path parameters:

Parameter	Type	Required	Description
credential_id	UUID	Yes	The credential to rotate

Request body: None.

Example:

curl -X POST https://api.arbitex.ai/api/v1/admin/credentials/3fa85f64-5717-4562-b3fc-2c963f66afa6/rotate \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Response (200 OK):

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "new_secret": "arx_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4",
  "grace_period_seconds": 3600,
  "previous_expires_at": "2026-04-04T19:00:00Z"
}

Response schema (RotateResponse):

Field	Type	Description
id	UUID	Credential identifier
new_secret	string	The new plaintext secret — returned once, never retrievable again
grace_period_seconds	integer	How long the old secret remains valid
previous_expires_at	datetime	When the old secret expires

Caution

Copy the new_secret value immediately. It cannot be retrieved after this response.

Rotation behavior:

• The current hash is demoted to previous_hash
• previous_expires_at is set to now + grace_period_seconds
• A new secret is generated and its hash becomes current_hash
• key_prefix is updated to the first 8 characters of the new secret
• Maximum 2 active secrets at any time (current + previous during grace)
• Rotating again during a grace period discards the oldest secret

Error responses:

Status	Condition
401 Unauthorized	Missing or invalid Bearer token
403 Forbidden	Caller does not have admin role
404 Not Found	Credential does not exist
409 Conflict	Credential is not active (already revoked or expired)

---

Revoke credential

DELETE /api/v1/admin/credentials/{credential_id}

Immediately invalidates both the current and previous secrets. Sets credential status to revoked. This action is irreversible.

Path parameters:

Parameter	Type	Required	Description
credential_id	UUID	Yes	The credential to revoke

Request body: None.

Example:

curl -X DELETE https://api.arbitex.ai/api/v1/admin/credentials/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Response: 204 No Content

Revocation behavior:

• Status changes to revoked
• revoked_at timestamp is set
• previous_hash is cleared — grace-period secrets are invalidated immediately
• All clients using this credential will fail authentication instantly

Error responses:

Status	Condition
401 Unauthorized	Missing or invalid Bearer token
403 Forbidden	Caller does not have admin role
404 Not Found	Credential does not exist

---

See also

• Credential Management — admin guide with operational procedures
• Key Rotation Integration Guide — developer guide for CredentialService
• API Keys — legacy API key management
• OAuth Clients API — OAuth-specific client configuration
• SCIM Provisioning API — SCIM-specific provisioning endpoints