15.2Choosing the directory

An installation can manage several Active Directory connections. Every request that touches a directory must say which one.

With an API key: X-Client-Id

An API key reaches a directory through a binding: a link between the key and one Active Directory connection, identified by a Client ID that is set when the key is linked in the Directory section of its settings page (Chapter 12). Send that Client ID in the X-Client-Id header on every directory request:

X-API-Key: <your API key>
X-Client-Id: hr-sync

The gateway checks that:

• a binding with that Client ID exists — otherwise 400 with "error": "Invalid X-Client-Id";
• the binding belongs to the API key making the request — otherwise 403 "The provided X-Client-Id does not belong to the authenticated API key.";
• the key's owner may still use that directory — otherwise 403 "The directory this API key is bound to is no longer available to the key's owner."

These three answers are short JSON objects with error and message, not problem details (see "Error responses" below).

A key's directory is a property of the key: there is no way for an API-key caller to choose a different directory per request.

Requests that do not touch a directory — for example GET /operations/{id} or GET /metadata — do not need X-Client-Id.

With a bearer token: X-AD-Connection-Id

A caller authenticated with a bearer token selects the directory with the X-AD-Connection-Id header, containing the connection's ID. The connection must be one the person's active role may use; a header naming any other connection is ignored. X-Client-Id is ignored on requests that are not authenticated by an API key.