15.1Authentication

API keys (recommended)

An API key is the credential intended for integrations. You create one in the web console (see Chapter 12, API keys) and send it in the X-API-Key header on every request:

GET /api/ad/users/3f2504e0-4f89-11d3-9a0c-0305e82c3301 HTTP/1.1
Host: gateway.example.com
X-API-Key: <your API key>
X-Client-Id: hr-sync

An API key acts as the person who owns it, limited by the role assigned to the key:

• The key's permissions are its role's permissions intersected with what the owner holds at the time of the request. If the owner loses a permission, the key loses it immediately. If the owner's account is deactivated, the key can do nothing.
• An API key is a machine credential. Its changes to Active Directory are checked against the key's supervision level and may be queued for a person's approval (see "Changes that wait for approval" below).
• If the key has Allowed addresses, a request from any other address is refused with 401.
• Every change is recorded in the operations log under the owner, with the API key's name.

Bearer tokens

The machine surface also accepts a platform access token in the Authorization: Bearer <token> header. This is the token the gateway issues when a person signs in. It is short-lived and tied to a person's interactive sign-in, so it suits tools a person runs by hand rather than unattended integrations. For anything that runs on its own, use an API key.

An API key cannot be sent as a Bearer token; it is read only from X-API-Key.

Access tokens issued to AI agents through the MCP sign-in (Chapter 13) are not accepted on /api, and platform access tokens are not accepted on the MCP endpoint. The two kinds of token are kept apart on purpose.

What an authentication failure looks like

Permission denials are deliberately generic: the response does not name the permission that was missing. Compare the operation with the role's permissions in the console (Chapter 11, Users, roles and permissions).