API Key
Need an API Key? Click here!
Authentication
API requests must include an AdeptID API key in the authentication header:
Set the HTTP header X-API-KEY: <AdeptID API Key> on the request.
Enable JSON content
AdeptID APIs send and respond to JSON. Set the following HTTP headers on all requests to enable sending and receiving JSON:
Content-Type: application/json
Accept: application/json
Compress Payloads
AdeptID recommends always compressing inbound payloads. The default inbound payload is limited to 20MB.
To send compressed payloads:
- Add or enable gzip compression in your client code. Many HTTP client libraries support this natively, but the payload can also be compressed as a step before sending the request.
- Set the HTTP header
Content-Encoding: gzipon the request.
Rate Limits
To ensure optimal performance for all customers and their end users, AdeptID enforces a limit of 3,000 requests per five-minute period. This limit is enforced per AdeptID API key, per API.
If a caller exceeds this threshold, additional requests may result in an HTTP status code of 429 ("Too Many Requests: Rate limit exceeded.") until usage falls below the allowed rate.
A basic technique to gracefully handle rate limiting is to watch for 429 status codes and build in a retry mechanism. The retry mechanism should follow an exponential backoff schedule to reduce request volume. Further, we also recommend including some randomness into the backoff schedule to avoid a "thundering herd" effect where groups of retry requests are occurring at the same time.
API Versioning
We periodically release new, dated versions of the API whenever we make breaking changes. We try to only make backwards compatible changes, but sometimes we have to make a breaking change to iterate on the API.
We consider the following changes backwards compatible:
- Adding new API endpoints
- Adding new optional parameters to existing endpoints
- Adding new data elements to existing responses
- Adding new errors
- Changing parameters from “Required” to “Optional”
API HTTP Status Codes
This table provides a reference for common HTTP status codes, their meanings, and guidance on whether requests should be resubmitted.
| Status Code | One-Line Summary | Should Request Be Resubmitted? |
|---|---|---|
| 200 | OK: Request succeeded. | No, request succeeded. |
| 201 | Created: Resource created successfully. | No, request succeeded. |
| 400 | Bad Request: Server could not understand request. | No, fix the request before retrying. |
| 401 | Unauthorized: Authentication required. | Yes, after providing credentials. |
| 403 | Forbidden: Server refuses to fulfill request. | No, do not resubmit. |
| 404 | Not Found: Resource does not exist. | No, unless resource is expected soon. |
| 405 | Method Not Allowed: HTTP method not supported. | No, use correct HTTP method. |
| 408 | Request Timeout: Server timed out waiting. | Yes, may retry. |
| 422 | Unprocessable Entity: Server understands request but cannot process it. | No, fix the request before retrying. |
| 429 | Too Many Requests: Rate limit exceeded. | Yes, after waiting as instructed. |
| 500 | Internal Server Error: Server encountered error. | Yes, may retry later. |
| 502 | Bad Gateway: Invalid response from upstream server. | Yes, may retry. |
| 503 | Service Unavailable: Server temporarily unavailable. | Yes, may retry after some time. |
| 504 | Gateway Timeout: Upstream server timed out. | Yes, may retry. |
Summary Notes
- 2xx codes (200, 201): Success responses - no need to resubmit
- 4xx codes (400, 401, 403, 404, 405, 408, 422, 429): Client errors - only retry after fixing the issue or waiting (for 429)
- 5xx codes (500, 502, 503, 504): Server errors - generally safe to retry, possibly after a delay