Skip to content
Arbitex Docs

API Keys

API keys provide long-lived credentials for programmatic access to the Arbitex API. Use them for service accounts, CI/CD pipelines, scripts, and any non-interactive client that cannot complete an interactive login flow.

For interactive user sessions, use session-based authentication (JWT access tokens issued after login) rather than API keys. API keys are intended for machine-to-machine access where a human is not present to authenticate.

Overview

Section titled “Overview”

Each API key is associated with the user account that created it. A key carries the permissions of that user — there is no mechanism to scope a key to a subset of the user’s permissions. For least-privilege access, create a dedicated service account with only the required role and generate keys under that account.

Keys authenticate requests via the Authorization header:

Authorization: Bearer <api_key>

Keys can be set to expire after a fixed number of days or remain non-expiring. They can be disabled temporarily without deletion, or revoked permanently. Admins can view and revoke keys across all users.

Generating a key

Section titled “Generating a key”

Via the API

Section titled “Via the API”
Terminal window
curl -X POST https://api.arbitex.ai/api/auth/api-keys \
  -H "Authorization: Bearer <your_session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "ci-pipeline-prod",
    "expires_in_days": 90
  }'

Omit expires_in_days to create a non-expiring key.

Response (APIKeyCreated):

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "key_prefix": "arb_a1b2",
  "description": "ci-pipeline-prod",
  "created_at": "2026-03-09T00:00:00Z",
  "last_used": null,
  "expires_at": "2026-06-07T00:00:00Z",
  "is_enabled": true,
  "api_key": "arb_a1b2c3d4e5f6..."
}

The api_key field contains the full plaintext key. This value is returned once and is not retrievable again. Copy it immediately and store it securely. If the key is lost, revoke it and generate a new one.

Via the UI

Section titled “Via the UI”

Navigate to Settings → API Keys → New API Key. Enter a description and optional expiry. The generated key is displayed once after creation — copy it before closing the dialog.

Key format

Section titled “Key format”

Keys are generated by generate_api_key(). The first 8 characters of the plaintext key form the key_prefix, which is stored in the database and displayed in key listings. The prefix lets you identify which key a credential belongs to without exposing the full value.

Example:

  • Full key: arb_a1b2c3d4e5f6g7h8...
  • Prefix: arb_a1b2 (first 8 characters)

The database stores only a hash of the key — the plaintext is never persisted after the creation response is returned.

Setting expiry

Section titled “Setting expiry”

Pass expires_in_days at creation to set an expiry date. The key becomes invalid after expires_at regardless of is_enabled state.

Terminal window
# Key expires in 30 days
curl -X POST https://api.arbitex.ai/api/auth/api-keys \
  -H "Authorization: Bearer <your_session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "short-lived-script",
    "expires_in_days": 30
  }'
Terminal window
# Non-expiring key (omit expires_in_days)
curl -X POST https://api.arbitex.ai/api/auth/api-keys \
  -H "Authorization: Bearer <your_session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "long-running-service"
  }'

Expiry cannot be changed after creation. To change the expiry of an existing key, revoke it and generate a replacement.

Listing keys

Section titled “Listing keys”

Returns metadata for all keys owned by the authenticated user. The plaintext key and hash are not included.

Terminal window
curl https://api.arbitex.ai/api/auth/api-keys \
  -H "Authorization: Bearer <your_session_token>"

Response:

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "key_prefix": "arb_a1b2",
    "description": "ci-pipeline-prod",
    "created_at": "2026-03-09T00:00:00Z",
    "last_used": "2026-03-09T12:34:56Z",
    "expires_at": "2026-06-07T00:00:00Z",
    "is_enabled": true
  }
]

Use last_used to identify stale keys that are candidates for rotation or revocation.

Disabling vs. revoking a key

Section titled “Disabling vs. revoking a key”

Disabling (is_enabled: false) prevents the key from authenticating requests without deleting it. The key can be re-enabled. Use this to temporarily suspend access — for example, while investigating a suspected compromise before determining whether to revoke.

Terminal window
# Disable a key
curl -X PATCH https://api.arbitex.ai/api/auth/api-keys/{key_id} \
  -H "Authorization: Bearer <your_session_token>" \
  -H "Content-Type: application/json" \
  -d '{"is_enabled": false}'


# Re-enable a key
curl -X PATCH https://api.arbitex.ai/api/auth/api-keys/{key_id} \
  -H "Authorization: Bearer <your_session_token>" \
  -H "Content-Type: application/json" \
  -d '{"is_enabled": true}'

Revoking (DELETE) permanently removes the key from the database. The key is immediately invalid and cannot be recovered. There is no soft-delete — deletion is final.

Terminal window
curl -X DELETE https://api.arbitex.ai/api/auth/api-keys/{key_id} \
  -H "Authorization: Bearer <your_session_token>"

Returns 204 No Content on success.

ActionReversibleKey removed from DBUse when
DisableYesNoTemporary suspension, investigation
Revoke (DELETE)NoYesConfirmed compromise, decommissioning

Key rotation procedure

Section titled “Key rotation procedure”

Rotate keys on a regular schedule or immediately after a suspected exposure. The procedure ensures no downtime for dependent services.

  1. Generate a new key under the same user account, using a description that identifies it as the replacement:

    Terminal window
    curl -X POST https://api.arbitex.ai/api/auth/api-keys \
      -H "Authorization: Bearer <your_session_token>" \
      -H "Content-Type: application/json" \
      -d '{
        "description": "ci-pipeline-prod-2026-03",
        "expires_in_days": 90
      }'

  2. Copy the new key from the api_key field in the response.

  3. Update all clients — CI/CD pipelines, environment variables, secrets manager entries — to use the new key. Verify each service is authenticating successfully with the new key before proceeding.

  4. Revoke the old key:

    Terminal window
    curl -X DELETE https://api.arbitex.ai/api/auth/api-keys/{old_key_id} \
      -H "Authorization: Bearer <your_session_token>"

Do not revoke the old key until all clients have been confirmed to use the new one. Running both keys in parallel briefly is safe — the old key remains valid until it is explicitly deleted.

Admin operations

Section titled “Admin operations”

Users with the admin role can list all API keys across the platform and revoke any user’s key. Admin endpoints use the /api/admin/api-keys prefix.

List all keys

Section titled “List all keys”

Returns metadata for all API keys across all user accounts. Useful for auditing active credentials, identifying stale keys, and enforcing rotation policies.

Terminal window
curl https://api.arbitex.ai/api/admin/api-keys \
  -H "Authorization: Bearer <admin_session_token>"

Response format is the same as the user listing — metadata only, no plaintext key or hash.

Revoke any user’s key

Section titled “Revoke any user’s key”

Admins can hard-delete any key regardless of which user owns it. The operation is identical in effect to a user revoking their own key: immediate invalidation, permanent removal from the database.

Terminal window
curl -X DELETE https://api.arbitex.ai/api/admin/api-keys/{key_id} \
  -H "Authorization: Bearer <admin_session_token>"

Returns 204 No Content on success.

Use this during incident response to immediately invalidate a compromised credential without requiring access to the key owner’s account.

Security recommendations

Section titled “Security recommendations”

Store keys in a secrets manager. Do not store API keys in source code, environment files committed to version control, or CI/CD configuration in plaintext. Use a secrets manager (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault) and inject the value at runtime.

Set expiry dates on all keys. Non-expiring keys remain valid indefinitely unless explicitly revoked. Prefer keys with a defined expiry — 30 to 90 days for most use cases — and automate rotation before expiry. Reserve non-expiring keys for cases where automated rotation is not feasible.

Use dedicated service accounts. Do not generate API keys under personal user accounts. Create a service account with the minimum required role and generate keys under that account. If the service account is decommissioned, all associated keys are revoked when the account is removed.

Audit last_used regularly. Keys that have not been used in 30 or more days are candidates for revocation. Use the admin listing endpoint to identify and clean up stale credentials across the platform.

Revoke immediately on exposure. If a key is exposed — in logs, a public repository, or a compromised system — revoke it immediately using DELETE. Do not rely on disabling alone; a disabled key can be re-enabled. After revoking, audit access logs to assess the scope of any unauthorized use.

Rotate on a fixed schedule. Even without a known exposure, rotate keys on a regular schedule (quarterly at minimum). Document the rotation schedule and automate the process where possible.

See also

Section titled “See also”