JWT bearer

How to execute the authorization flow and get your access token

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.

By including a scope in the access token request, all the resources that you fetch are automatically filtered.

The JWT bearer flow is available for for enterprise plans only.

At a high level, the JWT bearer token authorization grant follows the steps listed below:

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

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

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

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

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

Creating the JWT assertion

The assertion parameter must contain a single JWT encoded with an algorithm of your choice. Populate the https://commercelayer.io/claims key with an array of objects to pass all the information you need, 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.

{
  "https://commercelayer.io/claims": {
    "owner": {
      "type": "Customer",
      "id": "zxcVBnMASd"
    },
    "custom_claim": {
      "foo": "bar"
    }
  },
  "iat": 1707238036,
  ...
}

Invalid assertions

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

Getting an access token

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.

Request

POST https://auth.commercelayer.io/oauth/token

Arguments

Body parameter	Type	Required	Description
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).
assertion	String	Required	A single JSON Web Token (learn more). Max size is 4KB.

Examples

Sales channel

Request

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:

curl -g -X POST \
  'https://auth.commercelayer.io/oauth/token' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
  "client_id": "{{your_client_id}}",
  "client_secret": "market:id:xYZkjABcde",
  "assertion": "{{your_jwt_assertion}}"
}'

Response

On success, the API responds with a 200 OK status code, returning the requested access token and owner info, along with a refresh token:

{
    "access_token": "acC3sSt0K3Nwrt6kic7.abc4bnm5...",
    "token_type": "bearer",
    "expires_in": 7200,
    "refresh_token": "r3fResHt0k3nvbn7mnr9ert123",
    "scope": "market:all",
    "created_at": 123456789,
    "owner_id": "zxcVBnMASd",
    "owner_type": "customer"
}

The issued token's payload will have the following structure:

{
  "organization": {
    "id": "mzRmbZFPyO",
    "slug": "your-org-slug",
    "enterprise": true,
    "region": "eu-west-1"
  },
  "application": {
    "id": "jpYdqiDvMJ",
    "client_id": "cL13nT1Df7f7619d235e4d94b9ab",
    "kind": "sales_channel",
    "public": true
  },
  "custom_claim": {
    "foo": "bar"
  },
  "owner": {
    "id": "zxcVBnMASd",
    "type": "Customer"
  },
  "scope": "market:all",
  "exp": 1708098399,
  "test": true,
  "rand": 0.3594449293000671,
  "iat": 1707493599,
  "iss": "https://auth.commercelayer.io"
}

JWT single sign-on

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.

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

This feature is available for enterprise plans only. Read this blog post to see an example of how to implement SSO with Commerce Layer, using Auth0 and Next.js.

Single Sign-On with Commerce Layer Using Next.js and Auth0Commerce Layer