API Key Management¶

API keys provide machine-to-machine authentication for CI/CD pipelines, automation scripts, Terraform providers, and other non-interactive integrations. This guide covers creating, authenticating with, scoping, rotating, and revoking API keys.

Key Format¶

All ARX API keys use the prefix arx_k1_ followed by a random string:

arx_k1_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

The prefix identifies the key version (k1) and makes keys easy to detect in secrets scanning tools. The raw key is never stored in the database -- ARX computes a SHA-256 hash of the key and stores only the hash in the api_keys table.

Creating API Keys¶

Create an API key by calling the API keys endpoint. The creating user's organization and role context are associated with the key.

curl -X POST "https://api.arxsec.io/v1/api-keys" \
  -H "Authorization: Bearer <your-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline - Production",
    "expires_at": "2027-01-01T00:00:00Z"
  }'

The response includes the raw API key. This is the only time the key value is returned. Store it securely.

{
  "id": "a1b2c3d4-...",
  "key": "arx_k1_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "name": "CI/CD Pipeline - Production",
  "org_id": "e5f6a7b8-...",
  "created_by": "f7g8h9i0-...",
  "expires_at": "2027-01-01T00:00:00Z",
  "created_at": "2026-04-11T12:00:00Z"
}

Lost keys cannot be recovered. A new key must be created.

Authenticating with API Keys¶

Include the API key in the X-API-Key HTTP header:

curl "https://api.arxsec.io/v1/agents" \
  -H "X-API-Key: arx_k1_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

When the X-API-Key header is present, it takes precedence over any Authorization: Bearer header. The API key is validated before JWT authentication is attempted. The key is SHA-256 hashed and compared against stored hashes, and the system verifies the key has not been revoked or expired.

Scoping and Permissions¶

API keys inherit the RBAC role of the user who created them. The key's permissions cannot be changed after creation.

Creator Role	Key Permissions
`admin`	Full access to all endpoints
`deployer`	Deploy, manage agents, create API keys, and read operations
`auditor`	Read-only access to audit logs and reports
`viewer`	Read-only access to agents and status

To create a key with restricted permissions, create a dedicated service account user with the desired role, authenticate as that user, and create the API key. To change the scope of an existing key, revoke it and create a new one from a user with the desired role.

Expiration¶

The expires_at field is optional. If set, the API rejects requests with the key after the expiration timestamp with 401 API key has expired. If not set, the key does not expire.

Best practice for production deployments:

Set expiration dates on all keys (90 days recommended).
Rotate keys before they expire.
Monitor the last_used_at field to identify unused keys.

Rotation¶

To rotate a key:

Create a new API key with the same name and scope.
Update your CI/CD pipeline or integration to use the new key.
Verify that the new key works correctly.
Revoke the old key.

ARX tracks the last_used_at timestamp for each key. After rotating, monitor this field on the old key to confirm it is no longer in use before revoking it.

Revocation¶

Revoke a key by calling the delete endpoint:

curl -X DELETE "https://api.arxsec.io/v1/api-keys/<key-id>" \
  -H "Authorization: Bearer <your-jwt>"

Revoked keys are soft-deleted by setting the revoked_at timestamp. Any subsequent request using a revoked key receives a 401 Unauthorized response. Revocation is immediate and cannot be undone.

Usage Tracking¶

Every API key authentication updates the last_used_at timestamp on the key record. All actions performed with an API key are logged to the audit trail with the identity of the key's creator.

Best Practices¶

Use descriptive names that identify the integration (e.g., "GitHub Actions - Staging", "Terraform Cloud - Production").
Set expiration dates on all keys.
Create dedicated service account users for automation keys rather than using personal accounts.
Store keys in a secrets manager (AWS Secrets Manager, HashiCorp Vault, GitHub Actions secrets). Never commit keys to source control.
Regularly audit the API keys list and revoke unused keys.
Use the minimum required role for each integration.

Troubleshooting¶

Symptom	Cause	Resolution
`401 Invalid API key`	Key not found or revoked	Verify the key value and check if it has been revoked.
`401 API key has expired`	Key past its `expires_at` timestamp	Create a new key and update your integration.
`403 Requires one of roles: admin`	Key inherits insufficient permissions	Create a new key from an account with the required role.