JWT bearer
How to execute the authorization flow and get your access token
Last updated
Getting started
How to execute the authorization flow and get your access token
Last updated
Commerce Layer, through OAuth2, provides the support of token exchange in the on-behalf-of (delegation) scenario which allows, for example, to make calls on behalf of a user and get an access token of the requesting user without direct user interaction. Sales channels and webapps can accomplish it by leveraging the JWT Bearer flow, which allows a client application to obtain an access token using a JSON Web Token (JWT) assertion.
The JWT bearer flow is available for enterprise plans only.
At a high level, the JWT bearer token authorization grant follows the steps listed below:
Obtaining a JWT assertion — The client application creates a JWT assertion, which is a digitally signed JSON object containing information about the client and the user on whose behalf the access token is being requested. This JWT assertion can include information such as the issuer (typically the client), the owner (the user on whose behalf the request is made), expiration time, and any other relevant claims. Custom claims can also be added.
Requesting an access token — The client sends a token request to the Commerce Layer authorization endpoint, including the JWT assertion as part of the request. This request must include the grant type indicating it's a JWT bearer token request, the assertion itself, and any additional parameters required.
Validating the JWT assertion — Commerce Layer decodes the JWT assertion without verifying its signature but ensuring its integrity (e.g. checking that the assertion is well-formed and not too big, that the user exists and that the client is authorized to request an access token on behalf of the specified user).
Issuing an access token — If the JWT assertion is valid, Commerce Layer Auth API issues an access token to the client application. This access token represents the authorization granted to the client to access Commerce Layer resources on behalf of the user specified in the JWT assertion.
Using the access token — The client application can now use the access token to make authorized requests to Commerce Layer resources endpoints on behalf of the user, provided that the token has not expired or been revoked.
The assertion parameter must contain a single JWT encoded with an algorithm of your choice. Populate the https://commercelayer.io/claims object with the keys you need to pass all the desired information, such as:
owner — the customer or user you want to make the calls on behalf of.
custom_claim — any other information (key/value pairs) you want to enrich the token with.
The provided assertion is decoded without verifying its signature. Anyway, the token request will fail if the assertion is malformed or doesn't meet specific requirements. For example, the API will return a 400 Bad request error:
If the provided assertion resource owner doesn't exist.
If the JWT assertion byte size is too big (the maximum allowed size is 4KB).
To get an access token using the urn:ietf:params:oauth:grant-type:jwt-bearer grant type, send a POST request to the /oauth/token endpoint, passing the API client credentials in the request body.
For security reasons, the JWT bearer flow requires a client secret, even for sales channels.
POST https://auth.commercelayer.io/oauth/token
grant_type
String
Required
urn:ietf:params:oauth:grant-type:jwt-bearer
client_id
String
Required
Your client ID (from your API credentials).
client_secret
String
Required
Your client secret (from your API credentials).
scope
String
Optional
Your access token scope (market, stock location).
The following request tries to get an access token for a sales channel API client on behalf of the customer identified by the ID "zxcVBnMASd", using the JWT bearer grant type with the assertion above:
The issued token's payload will have the following structure:
Commerce Layer lets you authenticate users in your systems and use SSO with JWT so that a user is automatically verified with an identity provider of your choice (such as Auth0, Okta, or even a custom one) when they sign in. To do that you can leverage the JWT bearer flow with the correct assertion.
On success, the API responds with a 200 OK status code, returning the requested access token and owner info, along with a :
The customer must exist (or be created) in Commerce Layer. In order to use a customer token to manage registered customers, make sure that you have defined a password for the in Commerce Layer. Otherwise, some customer account functionalities may be unavailable (e.g. payment methods won't be saved in the customer wallet and cannot be reused). For security reasons, we strongly recommend choosing strong/random passwords.