API key best practices

API keys give programmatic clients long-lived credentials to authenticate against the Arbitex API. This guide covers how to create and manage keys safely, how to rotate them without downtime, and how to monitor for unused or compromised keys.

For the admin perspective on API key governance across an org — including revoking other users’ keys and auditing all keys in the org — see API key management.

Creating an API key

Navigate to Settings → API Keys → New API Key.

What to set at creation

Description — give every key a description that identifies its purpose and the service that uses it. Use a naming convention that includes the service name and environment:

data-pipeline-prod
ci-integration-staging
analytics-service

A key with no description is impossible to audit later. You cannot determine which service owns an unnamed key without checking its last_used timestamp and matching it against deployment logs.

Expiry — set an expiry date for all keys. Enter the number of days until expiry in the Expires in (days) field. Leave it blank only for long-running services where automated rotation is not yet feasible.

Recommended expiry ranges:

Use case	Expiry
CI/CD integration tests	30 days
Service-to-service integrations	90 days
Long-running background services	180 days (maximum before forced rotation review)
Non-expiring	Avoid — use only when rotation is technically infeasible

Copy the key immediately

After creation, the portal shows the full key value once. Copy it to your secrets manager before closing the dialog. The plaintext key is not stored and cannot be retrieved again.

arb_a1b2c3d4e5f6...

The key prefix (arb_a1b2) is stored and shown in key listings. Use the prefix to match a key you find in a log or config file to the corresponding record without exposing the full value.

If you close the creation dialog without copying the key, revoke it and create a replacement.

Scoping keys to minimize access

Arbitex does not support fine-grained permission scopes on individual keys — a key carries the full permissions of the user account that created it.

To achieve least-privilege access:

Use service accounts. Create a dedicated user account for each service or team (e.g., svc-data-pipeline, svc-ci). Assign it the minimum required role — user for inference-only workloads. Generate keys under the service account rather than your personal account.

Personal account keys are tied to your identity. If your account is deprovisioned, keys you created stop working. Service account keys have an independent lifecycle.

One key per environment. Create separate keys for staging and production. This allows you to rotate the staging key without affecting production, and to revoke a compromised staging key without disrupting live traffic.

Example key structure:

Service account	Key description	Purpose
`svc-pipeline-prod`	`pipeline-prod-2026-06`	Production inference requests
`svc-pipeline-staging`	`pipeline-staging-2026-06`	Staging inference requests
`svc-ci`	`ci-integration-2026-06`	CI/CD integration tests

Storing keys securely

Do not embed API keys in:

Source code or configuration files committed to version control
CI/CD pipeline configuration in plaintext (environment variables in YAML files visible to all contributors)
.env files that may be accidentally committed
Log output or error messages

Use a secrets manager to store and inject keys at runtime:

Azure Key Vault — inject via managed identity or Key Vault references
AWS Secrets Manager — inject via IAM role access at runtime
HashiCorp Vault — inject via agent or direct API at startup
Kubernetes Secrets — mount as environment variables or files; enable encryption at rest

If a key appears in a log, a code repository, or a compromised system, revoke it immediately. Do not rely on disabling alone — a disabled key can be re-enabled.

Key rotation

Rotate keys on a fixed schedule or immediately after any suspected exposure.

Scheduled rotation procedure

Create a replacement key under the same service account with an updated description (include the rotation date):

Navigate to Settings → API Keys → New API Key, enter a description like pipeline-prod-2026-09, and set an expiry date. Copy the key value.
Store the new key in your secrets manager.
Update consumers. Update environment variables, Kubernetes secrets, or CI/CD secrets to use the new key. Deploy the updated configuration.
Verify the new key works. Confirm that each service authenticates successfully using the new key before revoking the old one. Check the last_used timestamp on the new key — it should update once the first request authenticates.
Revoke the old key. In Settings → API Keys, locate the old key by its prefix and description, then click Revoke. Confirm the revocation.

Running both keys briefly in parallel is safe — they are independent credentials. Do not revoke the old key until all consumers are confirmed to be using the new one.

Emergency rotation (suspected compromise)

If you suspect a key has been exposed:

Revoke it immediately — do not wait to verify. Revocation is immediate.
Create a replacement key.
Review audit logs for requests made with the compromised key prefix. Contact your admin to run an audit log export filtered to that key’s usage window.
Update consumers with the replacement key.

Monitoring expiry

The key listing in Settings → API Keys shows the Expires column for each key. Keys that are approaching expiry or have already expired appear with their expiry date visible.

An expired key returns 401 Unauthorized on every request, regardless of its enabled/disabled state. There is no grace period after expiry.

Check your key expiry dates:

30 days before expiry — begin the rotation procedure. Allow time to update all consumers before the key expires.
At expiry — the key stops working. If you have not rotated yet, any services using it will fail immediately.

Expiry cannot be extended on an existing key. To change the expiry, revoke the old key and create a replacement with the new expiry date.

Monitoring last-used

Each key shows a Last Used timestamp updated each time the key successfully authenticates a request.

Use the last-used timestamp to identify:

Condition	Action
Key unused for 30+ days	Candidate for revocation — the service may be decommissioned or the key may be orphaned
Key with no last-used value	Never used — may be safe to revoke unless the service has not yet launched
Key last used before a known deployment	Verify the service updated to a newer key or investigate whether the old key is still in use

Keys with no last_used value that have been active for more than 30 days are likely orphaned. Revoke them if you cannot identify an owner.

Disabling vs. revoking

Action	What it does	Reversible
Disable	Prevents the key from authenticating. The key record remains.	Yes — re-enable any time
Revoke	Permanently deletes the key record. Immediate effect.	No

Use Disable when you want to temporarily block a key while investigating a potential compromise, before deciding whether to revoke. Use Revoke when you are certain the key should be permanently invalidated.

In Settings → API Keys, click the status badge (Active/Disabled) to toggle, or use the Revoke action to permanently delete.

Checklist

Before putting a key into production:

Description identifies the service and environment
Expiry date set
Key stored in a secrets manager, not in code or config files
Service account used (not a personal account)
Rotation schedule documented and scheduled