Skip to main content

Minting and Managing API Keys

Minting a Key​

  1. Log in to Align and navigate to Settings → Developer → API Keys.
  2. Click Create Key.
  3. Give the key a descriptive name (e.g. prod-sync or ci-read).
  4. Choose a scope:
    • Organisation — the key can act on every project in your workspace. Admins only.
    • Project — the key is restricted to a single project. Available to admins and engineering roles.
  5. Click Create.
  6. Copy the key now. It is shown only once. Only the prefix (ako_xxxxxxxx) remains visible afterward.

Store the key in a secrets manager (1Password, AWS Secrets Manager, GitHub Actions secrets, Doppler). Never commit it to a repository.

Using Your Key​

Send the key as either header:

# Recommended
curl https://app.alignsoft.us/api/v1/me \
  -H "Authorization: Bearer ako_your_key_here"

# Equivalent
curl https://app.alignsoft.us/api/v1/me \
  -H "X-API-Key: ako_your_key_here"

A successful response:

{
  "apiKeyId": "f17d33b9-...",
  "keyName": "prod-sync",
  "keyPrefix": "ako_9311c954",
  "organizationId": "ec597dd5-...",
  "scope": "organization",
  "scopedProjectId": null,
  "permissions": null,
  "createdByUserId": "69ecc6c3-...",
  "lastUsedAt": "2026-05-14T10:00:00.000Z"
}

Rate Limits​

API keys are subject to a 600 requests / minute sliding-window rate limit per key. Every response includes:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 597
X-RateLimit-Reset: 60

A 429 rate_limit response includes a Retry-After header. Back off and retry after that many seconds.

Revoking a Key​

  1. Go to Settings → Developer → API Keys.
  2. Find the key by its prefix or name.
  3. Click Revoke.

Revoked keys immediately respond 401 key_revoked on all subsequent requests.

Key Rotation Best Practice​

  1. Create a new key.
  2. Deploy the new key to your systems.
  3. Verify traffic is flowing through the new key.
  4. Revoke the old key.

This zero-downtime rotation ensures no request is dropped during the switch.

Full API Reference​

See the API Reference for all available endpoints, request/response schemas, and Try-It interactive examples.