Authorization code

How to execute the authorization flow and get your access token

The authorization code flow enables 3rd-party applications to access resources on behalf of a user without needing to expose their credentials. This flow helps maintain security by keeping the user's credentials confidential and allowing for granular control over the scope of access granted to 3rd-party applications. Here's a step-by-step breakdown of how the authorization code flow works:

1. User authorization request — The client application redirects the user to Commerce Layer authorization server with a request to authorize the application. This request includes the client ID, the requested scope of access, a redirect URI (where the user will be sent after authorization), and the response type set to code.

2. User authentication and authorization: The authorization server prompts the user to log in and authenticate themselves (if they're not already logged in). Once authenticated, the user is asked to authorize the 3rd-party application to access the requested resources.

3. Authorization code response: If the user grants authorization, the authorization server generates an authorization code and sends it back to the client via the redirect URI specified earlier. This code is a short-lived token that can only be exchanged for an access token by the client with the authorization server.

4. Authorization code exchange: Upon receiving the authorization code, the client application makes a request to Commerce Layer's Auth API token endpoint, including the authorization code, client ID, client secret, the redirect URI used earlier, and the same scope used to get the authorization code.

5. Access token response: The authorization server verifies the authenticity of the authorization code, client credentials, and redirect URI. If everything checks out, it responds with an access token and a refresh token. The access token is a bearer token that grants the 3rd-party application access to the requested resources on behalf of the user.

6. Resource access: The client application can now use the access token to make authorized requests to Commerce Layer Core API resources.

7. Token refresh: If the access token expires or becomes invalid, the client application can use the refresh token to request a new access token without requiring the user to re-authenticate. This helps in maintaining seamless access to resources.

In summary, the authorization_code grant type is used by webapps to exchange an authorization code for an access token. As you can see from the detailed steps above, unlike the other grant types, the authorization code flow requires two main connected actions:

• Getting an authorization code (steps 1-3)

• Exchanging the authorization code for an access token (steps 4-5)

Getting an authorization code

To request authorization from the user and get an authorization code, create an authorization request link for the user to click on by adding the necessary query parameters (e.g. client credentials, response type, etc.) to the Commerce Layer dashboard /oauth/authorize endpoint.

The response type must be code.

For security reasons, authorization codes expire after 10 minutes. Their short-lived nature enhances security by limiting their potential for misuse if intercepted.

Request

GET https://dashboard.commercelayer.io/oauth/authorize

Arguments

Query parameter	Type	Required	Description
client_id	String	Required	Your application's client ID.
redirect_uri	String	Required	Your application's redirect URI.
scope	String	Optional	Your access token scope (market, stock location).
response_type	String	Required	code
state	String	Optional	A string that is carried through the whole flow and returned to the client.

The state parameter is an optional value but we strongly recommend adding it to your HTTP request since it is a critical security measure that helps prevent/mitigate certain types of attacks (e.g. CSRF, XSS, etc.) and ensures the integrity of the user's session during the authorization process. When the user is redirected back to your app, whatever value you include as the state will also be included in the redirect. This gives your app a chance to persist data between the user being directed to the authorization server and back again, such as using the state parameter as a session key.

It is important to note that what you get is not an access token. The only thing you can do with the authorization code is to make a request to get an access token.

Example

Webapp

To authenticate any users, ask them to visit the following URL. The request tries to get an authorization code, putting in scope the market identified by the ID "xYZkjABcde" and using "1a2b3c" as the state parameter:

GET https://dashboard.commercelayer.io/oauth/authorize?
  client_id={{your_client_id}}&
  redirect_uri={{your_redirect_uri}}&
  scope=market:id:xYZkjABcde&
  response_type=code&
  state=1a2b3c

If the client ID exists, the user is prompted to authorize the 3rd party application to access their data:

After the authorization, the browser is redirected to the redirect URI (e.g. https://yourdomain.com/redirect) with a code parameter in the URL:

https://yourdomain.com/redirect?code=auTHc0d3axy123mnb567&state=1a2b3c

Getting an access token

To get an access token using the authorization_code grant type, send a POST request to the /oauth/token endpoint, passing the API client credentials and the code you got from the previous step in the request body.

The scope must be the same passed as query parameters in the request you made to get the authorization code.

Request

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

Arguments

Body parameter	Type	Required	Description
grant_type	String	Required	authorization_code
code	String	Required	The authorization code that you got from the redirect URI query string.
client_id	String	Required	Your application's client ID.
client_secret	String	Required	Your application's client secret.
redirect_uri	String	Required	Your application's redirect URI.
scope	String	Optional	Your access token scope (market, stock location).

Example

Webapp

Request

The following request tries to get an access token for a webapp, using the authorization_code grant type with the code you got from the previous step:

curl -g -X POST \
  'https://auth.commercelayer.io/oauth/token' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "grant_type": "authorization_code",
  "code": {{your_authorization_code}},
  "client_id": {{your_client_id}},
  "client_secret": {{your_client_secret}},
  "redirect_uri": "{{your_redirect_uri}}",
  "scope": "market:id:xYZkjABcde"
}'

The returned scope is the same passed as a query parameter in the request you made to get the authorization code. If you didn't specify a scope, the returned scope will be market:all.

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:id:xYZkjABcde",
    "created_at": 123456789,
    "owner_id": "zxcVBnMASd",
    "owner_type": "user"
}