Accessing the AuthRocket API

This document covers how to make requests with the AuthRocket APIs (via *.authrocket.com). To access the LoginRocket API, see Accessing the LoginRocket API.

API Endpoint

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).

Request Headers

Accept

The API only sends JSON responses. All API requests must indicate that they are requesting JSON payloads:

Accept: application/json

Accept-Language

The Core API’s error messages may be localized. See localization for more details and supported locales.

Accept-Language: en

Authentication

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).

Content type

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

Default realm

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.

User agent

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>

Response Headers

Content type

Responses from the API will indicate the delivery of a JSON payload:

Content-type: application/json

Request ID

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.

X-Request-ID: rq_0vdbINw16QhITBp4iBhgX4

Status

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.