API keys

An Access Key authenticates your organization’s own automation against the Merge API and the MCP endpoint. Every call carries one in the Authorization header:

Authorization: Bearer <YOUR_API_KEY>

The word Bearer is required and case-sensitive. The key never appears anywhere else.

Employees are never handed one of these. Three other credentials are theirs instead: a Gateway key minted per synced Group and revealed once on their Keys tab, a device credential minted per machine by the desktop client or the Workforce CLI, and a personal access token they generate themselves for MCP clients that cannot complete an OAuth flow. Only employees provisioned through SCIM can hold that last one, and each holds at most one at a time.

Production and test

Test keys give you a clean sandbox. Credentials and tool calls made with a test key are isolated from production. The trade-off: a test key cannot read production data and a production key cannot read test resources, so mixing them up shows up as 404 not found on resources you are certain exist.

Manage both at Settings → API keys. Creating, rotating, and revoking requires the Manage organization API keys permission.

Generating keys

Master key. An organization’s one unnamed production key carries a master badge, reads as Full access, and has no Revoke key option. Click Regenerate secret to rotate it. Rotation invalidates the old value immediately, so propagate the new one everywhere before clicking, or you have an outage as long as it takes to redeploy. Not every organization has one, so an empty production list is normal until you add a key.

Additional production keys. Click Add key and name it. Hold as many as you need, so each service or environment carries its own credential. Each key’s overflow menu offers Copy key ID, Regenerate secret, and Revoke key, and the row summarizes its scope as its Tool Pack and employee restrictions.

Test keys. Same flow, named for what they are for: ci, alice-dev, staging-2.

Every key’s value is shown once at creation, production and test alike. Lose it and the only path is a replacement.

Expiry and restrictions

A key can carry an optional expiry date, set when you create it. The key stops working on that date, which suits a contractor’s access or a time-boxed migration. Production and test keys share one create dialog, so both take an expiry.

A key can also be restricted to specific Tool Packs, specific employees, or both, from the same dialog. Two things to know before you rely on it:

• Restrictions are enforced when the key makes a tool call, not on management operations. A restricted key can still read and write configuration through the API
• A key’s restrictions cannot be edited after creation. To change them, revoke the key and create a replacement

Rotation

Rotate production keys at least once a year, and immediately if you suspect one leaked.

The cleanest rotation adds a key rather than replacing one in place, so there is never a window with no valid credential deployed:

1. Create a new production key and copy its value.
2. Roll it out everywhere the old one is used: secret manager update, release, confirm.
3. Confirm traffic on the new key.
4. Revoke the old key.

Step 4 has one guard: you cannot revoke your organization’s last unrestricted production key, because that would leave nothing able to manage the others. Create the replacement first and the revoke goes through. The master key cannot be revoked at all, so rotating that one means regenerating it in place: roll the replacement out first, then click Regenerate secret, since the old value stops working the moment you do.

If a key has leaked publicly, by being committed to a repo or posted in a chat, revoke or regenerate first and roll out second. An outage costs less than someone else holding your key.

Minting keys through the API

Everything on the API keys page has an equivalent under /api/v1/access-keys/, which is how you mint short-lived keys per deployment instead of sharing one long-lived key.

A key you create through the API can be narrower than the key that created it, never wider. POST /api/v1/access-keys/ accepts tool_pack_ids, registered_user_ids, scopes, and either expires_at or expires_in, and each has to be a subset of the calling key’s own grant. A key limited to one Tool Pack cannot mint a key that reaches a second one.

Unlike the dashboard, the API expires keys by default: omit both expiry fields and the key expires 90 days out. Send "expires_at": null for one that never expires. The two scopes are runtime:all for MCP tool calls and management:all for the resource-management endpoints.

curl -X POST https://ah-api.merge.dev/api/v1/access-keys/ \
  -H "Authorization: Bearer $MERGE_AH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "nightly-reconcile",
    "tool_pack_ids": ["1d8b6f4a-1b3e-4f9b-9d3a-3a8e8b9c0d1f"],
    "scopes": ["runtime:all"],
    "expires_in": 3600
  }'

The key value comes back once, on the create response. After that only key_masked is readable.

The same subset rule governs POST /api/v1/access-keys/{key_id}/regenerate/ and POST /api/v1/access-keys/{key_id}/revoke/. A key can act on itself, or on a key whose grant it fully covers:

Anything else returns 403 with “Access key may only act on itself or on keys within its scope.” The response does not name the pair, so compare the two keys’ grants yourself when a rotation is refused.

Coverage rather than lineage is what makes this usable in both directions. Every key minted through the API is covered by the key that minted it, so a service can always rotate its own children, and keys created in the dashboard are covered by your unrestricted production key.

The expiry clause is the part to plan around: a one-hour scoped key cannot rotate your never-expiring production key, which is what stops a short-lived leak from becoming a permanent one. If a scoped service needs to rotate a long-lived key, give the service a long-lived key of its own rather than widening the scoped one.

Gateway keys are separate

Access Keys reach tools. Model traffic runs on Gateway keys, and the two are minted in different places.

Employee and Group Gateway keys are issued automatically on sync, so there is nothing to hand out. Rotate one from the employee’s Keys tab: rotation revokes and re-mints in a single step, and the replacement reveals once.

For automation that provisions Gateway keys itself, a management key is the credential to use. It creates, caps, and revokes Gateway keys but cannot call a model, which keeps the credential that provisions keys separate from the ones that spend money. Per-key spend limits and model allowlists are set the same way. See Management API keys.

Storage

Treat every key like any other secret.

• Do not commit them. A gitignored .env locally, a secret manager in deployed environments
• Do not expose them client-side. A production Access Key acts on behalf of your employees, so calls belong on a server you control
• Do not share them across environments or services. Each environment, and ideally each service, holds its own

The Audit trail records every key creation, regeneration, and revocation. When one key rotates another through the API, the entry names both the acting and the target key, so a rotation chain reads without correlating requests by hand.

Next

Bring your own OAuth app per Connector with Application credentials.