Credential Management

Arbitex uses a unified credential model for all secret types: OAuth client secrets, API keys, SCIM tokens, and client identity keys. Every credential type shares the same rotation, authentication, and revocation behavior — one table, one API surface, one set of operational procedures.

This page covers day-to-day credential operations from the admin perspective. For API details, see Credentials API Reference. For developer integration, see Key Rotation Integration Guide.

Credential types

All credential types are stored in the unified credentials table and managed through the same endpoints.

Type	Owner	Use case
`oauth_client`	OAuth client application	Machine-to-machine authentication via client credentials grant
`api_key`	User or service account	Programmatic API access for scripts, CI/CD, and integrations
`scim_token`	SCIM provisioning config	Identity provider directory sync (user and group provisioning)
`client_identity`	Client identity registration	Device-bound or service-bound identity attestation

Each credential record tracks:

Key prefix — first 8 characters of the secret (e.g., arx_a1b2), visible in listings for identification without exposing the full value
Status — active, revoked, or expired
Grace period — how long the previous secret remains valid after rotation (default: 1 hour)
Rotation history — when the credential was last rotated and by whom

Viewing credentials

List all credentials across the platform:

curl https://api.arbitex.ai/api/v1/admin/credentials \
  -H "Authorization: Bearer <admin_token>"

Filter by organization or type:

# Filter by org
curl "https://api.arbitex.ai/api/v1/admin/credentials?org_id=<uuid>" \
  -H "Authorization: Bearer <admin_token>"

# Filter by type
curl "https://api.arbitex.ai/api/v1/admin/credentials?type=api_key" \
  -H "Authorization: Bearer <admin_token>"

The response includes metadata only — secrets and hashes are never returned in listings.

Rotating credentials

Rotation generates a new secret and demotes the current secret to a grace-period backup. Both secrets are valid during the grace window, ensuring zero downtime for connected clients.

Trigger rotation via the admin API:

curl -X POST https://api.arbitex.ai/api/v1/admin/credentials/<credential_id>/rotate \
  -H "Authorization: Bearer <admin_token>"

Copy the new secret from the response. The new_secret field contains the plaintext — it is returned once and never retrievable again.

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

Update all clients that use this credential with the new secret. Verify each client authenticates successfully.
Wait for the grace period to expire (or proceed immediately if all clients are updated). The old secret automatically stops working after previous_expires_at.

Grace period behavior

During the grace period, both the current and previous secrets authenticate successfully. This is the key mechanism for zero-downtime rotation:

Time	Current secret	Previous secret
Before rotation	Valid	N/A
During grace period	Valid	Valid
After grace period expires	Valid	Invalid

Default grace period: 3600 seconds (1 hour)
Grace period is configurable per credential at creation time
Maximum active secrets: 2 (current + previous). Rotating again during a grace period replaces the previous secret — the oldest secret is discarded immediately
Secrets do not stack — there are never more than two valid secrets for a credential

Revoking credentials

Revocation immediately invalidates both the current and previous secrets. Use this for confirmed compromises or decommissioning.

curl -X DELETE https://api.arbitex.ai/api/v1/admin/credentials/<credential_id> \
  -H "Authorization: Bearer <admin_token>"

Returns 204 No Content on success.

Rotation vs. revocation

Action	Current secret	Previous secret	Reversible	Use when
Rotate	Replaced (new generated)	Demoted with grace window	No (but old secret has grace period)	Scheduled rotation, proactive security
Revoke	Invalidated	Invalidated	No	Confirmed compromise, decommissioning

For a suspected compromise where you need time to investigate, rotate first (clients keep working with the new secret), then revoke the old credential if the investigation confirms a breach.

Credential lifecycle

Created (active) → Rotated (active, grace period) → Rotated again → ... → Revoked

Creation — a new credential is generated with status active. The plaintext secret is returned once.
Rotation — current secret becomes previous (with grace period). New secret generated. Status stays active.
Revocation — status changes to revoked. Both current and previous secrets invalidated. revoked_at timestamp recorded.

Credentials can be rotated any number of times. Each rotation resets the grace window for the newly demoted secret.

Key format

All Arbitex-generated secrets use the arx_ prefix followed by 48 hex characters:

arx_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4

Prefix: arx_ — identifies the credential as Arbitex-issued
Key prefix (stored): first 8 characters (e.g., arx_a1b2) — used for identification in listings
Storage: only the SHA-256 hash is stored in the database. The plaintext is never persisted.

Security recommendations

Rotate on a regular schedule. Quarterly rotation is the minimum recommended cadence. Automate the process using the Credentials API.

Use the grace period wisely. The default 1-hour grace period gives sufficient time to update most client configurations. For complex environments with many consumers, consider setting a longer grace period at credential creation time.

Monitor rotated_at timestamps. Credentials that have never been rotated or were last rotated more than 90 days ago are candidates for immediate rotation.

Revoke immediately on confirmed compromise. Do not rely on rotation alone — rotation leaves the old secret valid during the grace period. For confirmed breaches, revoke to invalidate all secrets instantly.

Store secrets in a secrets manager. Use Azure Key Vault, AWS Secrets Manager, or equivalent. Never store plaintext secrets in source code, environment files committed to version control, or CI/CD configuration.