15.8Limits

Request size

A larger body is refused with 413 and the problem-details code Request.BodyTooLarge, with maxBodyBytes naming the limit. Administrators can change both values with RequestLimits:MaxBodyBytes and RequestLimits:MaxBatchBodyBytes.

Attributes in one write

Every create or update of a directory object is limited, across its attributes, replace, add, remove and clear bags together:

In a batch, each item is checked against these limits when its turn comes.

Organizational-unit account runs

Enabling or disabling the accounts in an organizational unit (POST /ad/organization-units/{id}/accounts/enable or /disable) changes at most 100 accounts per run. A larger selection is refused whole with OrganizationUnitAccounts.TooMany. Use GET /ad/organization-units/{id}/accounts/plan?action=disable&kinds=users&scope=oneLevel to preview a run without changing anything. A run that partly fails answers 207.

Rate limits

Requests are rate-limited per client IP address. When a limit is reached, the API answers 429 Too Many Requests with a Retry-After header saying how many seconds to wait.

/health is never rate-limited. Administrators can tune these under the RateLimiting configuration section, including per-path overrides. Behind a reverse proxy, the gateway only trusts the forwarded client address from proxies it is configured to know about; otherwise all requests count against the proxy's address.

Tip: Design integrations to search once and work through the results, rather than search once per item. Honour Retry-After on a 429 instead of retrying immediately.

OpenAPI and Swagger

The API is described by OpenAPI documents, one per surface: the machine document describes /api, and the browser document describes /rest. Integrators need only the machine document.

The interactive Swagger page and the OpenAPI documents are served only when the gateway runs in the Development environment, at /swagger. Production installations do not publish them. To generate a client or explore the API, use a development or test installation, or ask your vendor contact for the machine document.

Setting up an integration

To prepare an integration:

1. 1Ask an administrator to create a role with only the permissions the integration needs (Chapter 11).
2. 2Create an API key with that role (Chapter 12), and copy the key when it is shown.
3. 3On the key's settings page, link it to the Active Directory connection the integration manages (Directory section, Link AD Server), and copy the link's Client ID.
4. 4If the integration runs from known servers, list their addresses under Allowed addresses.
5. 5Decide with an approver which supervision level the key should have. An integration that must run unattended may need Act without asking; everything else should stay at Ask before destructive and security changes.
6. 6Test with a read request, then a harmless write, and check both in the operations log.