The AuthRocket API is https only. TLS 1.2+ is required.
The API endpoint varies according to the cluster used to provision your service. Your account’s endpoint URL will be displayed in the management portal next to your Secret API Key (Realm -> Integration -> API keys).
The API only sends JSON responses. All API requests must indicate that they are requesting JSON payloads:
The Core API’s error messages may be localized. See localization for more details and supported locales.
Authentication uses either a standard Authorization header or an AuthRocket-specific HTTP header:
Authrocket-Api-Key: ks_0ut5nPLwrV9PxSRGy8OMZI-e34b5ff952f5e43de641d6e96a9a5d58 OR Authorization: Bearer ks_0ut5nPLwrV9PxSRGy8OMZI-e34b5ff952f5e43de641d6e96a9a5d58
For the Authorization header, only Bearer tokens are supported. Basic and Digest auth are not supported.
API keys may be be created and managed in the management portal under Realm -> Integration -> API keys.
See also: Default Realm (below).
Payloads sent to the API via POST or PUT requests may be sent as JSON or as standard url-encoded form data. JSON payloads are recommended as they are much easier to read/debug when using nested data.
Content-type: application/json Content-type: application/x-www-form-urlencoded
If your app only uses a single realm, you may specify a default Realm ID via HTTP header. This is optional as
realm_id may always be passed as part of individual API calls.
When an API key is locked to a single realm, that realm will automatically be used as the default realm. There is no need to specify the default realm again.
If using more than one realm, do not set a default realm. Instead, send it as part of the request (via query param or request body).
The default realm may also be appended as part of the Bearer token (but
Authrocket-Realm is also still supported when using a Bearer token).
Authrocket-Realm: rl_0v1zTHXhtNgmDaXaDYSAqx OR Authorization: Bearer ks_0ut5nPLwrV9PxSRGy8OMZI-e34b5ff952f5e43de641d6e96a9a5d58,rl_0v1zTHXhtNgmDaXaDYSAqx
The realm ID can be found alongside the API key in the management portal under Realm -> Integration.
If you’re writing an AuthRocket library for use by 3rd-parties, a User-agent header with contact info for the library author(s) is required (a GitHub or other URL is fine). This enables us to reach out in the event we see something that needs to be addressed.
For everyone else, the User-agent header is optional, but adding one and including some kind of version identifier may be useful for your own debugging.
This field is logged without encryption or sanitization. Please keep this in mind before sending personally identifying information.
User-agent: <Your library or app, with URL or role email>
Responses from the API will indicate the delivery of a JSON payload:
All API responses will include X-Request-ID, which is unique to each request. If you have a question about a specific API call, sending the request ID will make it much easier for us to help you debug the issue.
API responses all deliver an appropriate HTTP
Status: header. The numeric portion of this status code should be checked before attempting to parse the body response. See Status codes for more details.