Creating and Managing API Keys

Every Public API request is authenticated with an API key. Keys belong to an organisation and are managed in Settings → Developer → API Keys (/admin/developer/keys). In the Partner Console the same page is Developer Portal → API Keys.

Who can create keys

Your role	What you can create
admin	Organisation-scoped keys. Admins see and manage every key in the organisation.
manager, developer, tech_lead, devops_engineer	Project-scoped keys, for a project you can access. You see and manage project keys for projects you can access.

Other roles cannot create keys.

Admins and managers reach the page from Settings → Developer. Developers, tech leads and DevOps engineers have no Settings link in the sidebar, so they open https://app.alignsoft.us/admin/developer/keys directly.

The Public API must be turned on for the organisation. Admins see a Public Developer API v1 switch at the top of the Developer page. When it is off, every key-authenticated request is refused with 403 feature_disabled.

Creating a key

1. Go to Settings → Developer → API Keys (or open /admin/developer/keys) and click Create key.
2. Enter a Name (for example prod-sync). If you are not an admin, choose the Project the key is restricted to.
3. Optional: click Customize to choose the key's permissions. If you leave it, the key gets the least-privilege default for its scope. See Authorization & Scopes.
4. Click Create.
5. Copy the key from the Copy your API key dialog. This is the only time the full key is shown. Afterwards the list shows only its prefix.

Organisation-scoped keys start with ako_ and project-scoped keys with akp_. The prefix shown in the list is the first 12 characters (for example ako_9311c954…).

Store the key in a secrets manager. Never commit it to a repository.

Using your key

Send the key in 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"

GET /api/v1/me describes the key you are using:

{
  "apiKeyId": "f17d33b9-...",
  "keyName": "prod-sync",
  "keyPrefix": "ako_9311c954",
  "organizationId": "ec597dd5-...",
  "scope": "organization",
  "scopedProjectId": null,
  "permissions": ["read:entry", "read:project", "write:entry"],
  "createdByUserId": "69ecc6c3-...",
  "lastUsedAt": "2026-10-14T10:00:00.000Z"
}

Rate limits

Each key has a sliding-window limit of 600 requests per minute. The same limit applies to the key's use of the MCP server. Every response carries:

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

X-RateLimit-Reset is the number of seconds until the window resets. When you exceed the limit, Align responds 429 with reason rate_limit and a Retry-After header. Wait that many seconds before retrying.

The Usage tab shows requests and errors per key for the last 24 hours.

Changing a key's permissions

Click the pencil icon on a key's row to open its permissions. Changes take effect on the key's next request; the secret does not change, so nothing needs redeploying.

A key with no permission list shows Full access (legacy) and can call everything its scope reaches. Keys created before per-key permissions existed are like this, and so, today, are the keys Align creates when a customer installs a Marketplace app (named Marketplace: …). Saving permissions on such a key replaces its unrestricted access with the list you choose, and it cannot be made unrestricted again.

Revoking a key

1. Go to Settings → Developer → API Keys.
2. Find the key by its name or prefix.
3. Click the trash icon on its row and confirm.

A revoked key is refused with 401 key_revoked on every later request. Revoking cannot be undone.

Rotating a key

1. Create a new key with the same permissions.
2. Deploy the new key to your systems.
3. Check that traffic is using the new key: its Last used time updates.
4. Revoke the old key.

Full API reference

See the API Reference for every endpoint and schema.