API Keys, Scopes & Rate Limits

Once you have issued an API key (see Authentication for basic setup), you can configure its scope and expiry to match your security requirements. Rate limiting is enforced by the platform and is not configurable per key.

Scopes

Each API key is assigned one or more scopes that determine which resources and operations it can access. Scopes follow a verb:resource pattern:

Scope hierarchy

• write: scopes do NOT grant read: — a key with write:products cannot list products. You must issue separate read and write scopes if both are needed.
• * (full access) grants all scopes and operations.
• No scope = no access (default behavior if no scope is selected).

Per-endpoint scopes

Minting a key with custom settings

When you issue a key, you can configure:

1. Name — A memorable label for the key (e.g., "HubSpot Sync", "Shopify Import").
2. Scopes — Choose specific scopes (e.g., read:products, write:contacts) or * for full access.
3. Expiry — Optional. Set the key to expire after N days (e.g., 30, 90, 365). If left blank, the key never expires.

Every key is limited to 120 requests/minute, enforced by the platform (not configurable).

Expiry behavior

• No expiry set — The key is valid indefinitely (until revoked).
• Expiry set — The key expires at the end of the configured date. After expiration, the key returns a 401 on every request.
• Revoked — You can revoke a key anytime from Settings → API keys. It returns a 401 immediately.

Rate limits

Each key is limited to 120 requests/minute, enforced by the platform (not configurable). The limit applies across all operations for that key.

• Within limit — Request succeeds (200, 207, etc.).
• Limit exceeded — Request fails with 429 Too Many Requests. Retry after the Retry-After response header.

Example: rate limit response

HTTP/1.1 429 Too Many Requests
Retry-After: 35
Content-Type: application/json

{
  "error": "Rate limit exceeded."
}

429 Too Many Requests
Retry-After: 35

{"error":"Rate limit exceeded."}

In this example, wait 35 seconds before retrying.

Error responses

401 Unauthorized

Returned when the API key is missing, invalid, malformed, expired, or revoked.

{
  "error": "Invalid or missing API key."
}

Causes:

• No Authorization header sent.
• Key is malformed (not alk_live_... format).
• Key is expired or revoked.

Action: Check your key, confirm it has not expired or been revoked, and ensure it matches your workspace.

403 Forbidden

Returned when the API key lacks the required scope for the operation.

{
  "error": "API key missing required scope: write:products."
}

Causes:

• Key has read:products but endpoint requires write:products.
• Key has write:contacts but endpoint requires write:deals.

Action: Verify the endpoint's required scope (see Per-endpoint scopes). If needed, issue a new key with the required scope.

429 Too Many Requests

Returned when the key's per-minute rate limit is exceeded.

{
  "error": "Rate limit exceeded."
}

Header: Retry-After: <seconds> indicates how long to wait before retrying.

Causes:

• The key has exceeded its rate limit (120 req/min, platform-enforced).

Action: Wait the number of seconds indicated by the Retry-After header, then retry. Consider implementing exponential backoff for resilience.

Best practices

1. Use role-based scopes — Issue a key with only the scopes required for the integration. Avoid using * unless necessary.
2. Set expiry dates — For temporary integrations or third-party services, configure a 30-, 90-, or 365-day expiry.
3. Monitor rate limits — If your integration regularly hits 429, add backoff/retry logic or spread requests over time; the 120 req/min limit is platform-enforced and cannot be raised per key.
4. Rotate keys regularly — Revoke old keys and issue new ones periodically (e.g., quarterly).
5. Store securely — Never commit API keys to version control. Use environment variables or a secrets manager.
6. Alert on 401/403 — If an integration starts returning 401 or 403, the key may have expired or been revoked. Set up monitoring to detect these errors.