Authenticate with JWT

Authenticating with JWT is our recommended method. If you haven’t already, check out our high-level summary for authentication with Redox.

To authenticate with JWT, you must complete these high-level steps.

  1. Generate a private/public key pair in the Redox dashboard.
  2. Request an access token from Redox.
  3. Store the access token in your own system.
  4. Initiate any API request with the access token in the header.

Check out the diagram for a visual version of these steps:

JWT authentication flow
JWT authentication flow

Now let's get into the nitty gritty for each step.

Generate a private/public key pair

To authenticate with a JWT, you must have a key pair with a private and public key.

Request an access token

You have two options for requesting an access token:

  • Use our Postman collection; or
  • Use an application of your choice.

Either way, the authentication steps are the same. If you choose to use Postman, complete the prep steps that we outline below. Otherwise, skip to the authentication steps.

Create an authentication request

Generate a signed request and send it to https://api.redoxengine.com/v2/auth/token via HTTP POST from your system. Redox validates the signature in the request, then sends back a response with the access token. You use this access token to make an API request to Redox.

Canada URL

If you're operating in Canada, you must tweak the Redox hostname slightly. All you need to do is add a ca in that URL like this: https://api.ca.redoxengine.com.

Expiration for access token

Just note that the access token we provide to you expires after 5 minutes. You can use this access token to make any API requests within 5 minutes, but if a request fails, it's likely that your access token has expired. You must send a new authentication request to generate a new access token.

If you have high traffic and don't want to disrupt your workflow, you can use a service to refresh your access token every 5 minutes.

If you have low traffic, you can run an authentication request prior to making any API request.

With Postman, the authentication request looks something like this:

With your own application, the request may look like this instead after following these steps:

  1. Copy the code example below.
  2. Make sure the axios and jose libraries are installed with npm i axios jose.
  3. Update the privateKeyPEM, clientId, and kid based on the signed request you generated previously.

For definitions of the parameters or values used in the code examples, check out the definitions below.

Header values

For the header, use content-type application/x-www-form-urlencoded.

Parameter
Required
Description
alg
Y
The JWA algorithm used for signing the authentication JWT. Note that we currently only support RS384.
kid
Y
The identifier of the key-pair used to sign this JWT. This identifier tells us which public key to use to verify the JWT.
typ
Y
This is the type of token request. Populate this with JWT.
jku
N
This field may be populated if you provided a JWKS URL in the Dashboard. If you provide it here, the URL should match what's saved in the Dashboard. Populate this with the TLS-protected JWKS URL, which contains the public key(s) that are accessible without authentication or authorization. If this field isn't present, Redox reverts to what's saved in the Dashboard.
Request parameters

Populate the request with the following parameters

Parameter
Required
Description
grant_type
Y
Populate this with client_credentials.
client_assertion_type
Y
If using the Postman collection, this value automatically populates.
If using your own application, populate this with urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion
Y
If using the Postman collection, this value automatically populates.
If using your own application, populate this with the signed authentication JWT value.
Body values
Parameter
Required
Description
iss
Y
The issuer of the JWT. This should be populated with the client_id of the key you created in the Dashboard. Keep in mind that this is the same value that's provided for the sub claim.
sub
Y
This should be populated with the client_id of the key you created in the Dashboard. Keep in mind that this is the same value that's provided for the iss claim.
aud
Y
The audience of the JWT. This should be populated with https://api.redoxengine.com/v2/auth/token.
iat
Y
The UTC timestamp for when the JWT was created (e.g.,1970-01-01T00:00:00Z UTC). This time must not be greater than 5 before exp.
exp
Y
The expiration UTC timestamp for the JWT (e.g., 1970-01-01T00:00:00Z UTC). This time must not be greater than 5 minutes in the future.
jti
Y
This is a nonce string value that uniquely identifies this JWT. Redox denies requests if the jti is reused within the lifetime of the JWT.

View an example of a valid JWT with all of these values populated.

If your request is populated correctly and Redox successfully validates your signature, Redox responds with an access token.

Initiate requests

You can now initiate requests with the access token in the Authorization HTTP header using the Bearer authentication scheme.