12.5Using an API key

The machine surface

Integrations call the API on its machine surface, under /api. With the default installation, where the API is published under /backend, the base address is:

https://gateway.example.com/backend/api/

Send the key in the X-API-Key header on every request. The machine surface accepts only explicit credentials: a browser's sign-in cookie is refused there, so a web page cannot borrow a person's session to call it. The console itself uses a separate surface, /rest, which is meant for the browser; integrations should always use /api.

Naming the directory

To act on Active Directory, a key must be linked to a directory (see Directory in Changing a key's settings), and each request must name that link with the X-Client-Id header, using the key's Client ID:

GET /backend/api/ad/users/3f2a9c1e-5b7d-4e2a-9f10-6c8d2b4a7e55 HTTP/1.1
Host: gateway.example.com
X-API-Key: ak_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
X-Client-Id: n8n-provisioning

• A request with an X-Client-Id that belongs to another key, or to no key, is refused.
• A key cannot choose a different directory per request. Its directory is a property of the key.
• If the owner's roles no longer reach the linked directory, requests naming the link are refused until the owner's access is restored or the key is linked to another directory.
• A request without X-Client-Id acts on no directory, so any directory operation in it fails.

The same request in PowerShell:

$headers = @{
    'X-API-Key'   = $env:GATEWAY_API_KEY
    'X-Client-Id' = 'n8n-provisioning'
}
Invoke-RestMethod -Method Get -Headers $headers `
    -Uri 'https://gateway.example.com/backend/api/ad/users/3f2a9c1e-5b7d-4e2a-9f10-6c8d2b4a7e55'

Tip: Keep the key out of scripts and source control. Read it from an environment variable or a secret store, as in the example above.

Responses an integration must handle

• 401 — the key is missing, wrong, expired or revoked, or the request came from an address not on the key's allowed list.
• 400 — the X-Client-Id matches no directory link.
• 403 — the key's role does not allow the operation, the X-Client-Id belongs to another key, or the owner can no longer use the linked directory. Permission refusals deliberately do not name the missing permission.
• 202 Accepted — the change was queued for approval because of the key's supervision level, a protected target or an always-ask pin. Nothing has been changed yet. The body carries an operationId, the reason it is waiting and a poll address; poll GET /api/operations/{id} until the operation is decided. Do not repeat the request, which would queue a second one. See Chapter 9, Operations log, approvals and waiting operations, and Chapter 15, REST API for integrators.

A key can never approve operations, not even one owned by an approver: approving and rejecting are decisions only a signed-in person can make in the console.

For the full API reference, see Chapter 15, REST API for integrators. For using a key from n8n, see Chapter 14, n8n integration.

Good practice

• Create one key per integration, named after it, so that revoking one never breaks another.
• Give each key the narrowest role that does the job, and link it to the one directory it needs.
• Set an expiry date, and an allowed-address list for keys used from fixed servers.
• Keep the default supervision, Ask before destructive and security changes, unless an unattended workflow genuinely cannot wait.
• Revoke a key as soon as it may have been exposed, then issue a new one.