Authorization code
How to execute the authorization flow and get your access token
Last updated
How to execute the authorization flow and get your access token
Last updated
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:
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
.
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.
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.
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.
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.
Resource access: The client application can now use the access token to make authorized requests to Commerce Layer Core API resources.
Token refresh: If the access token expires or becomes invalid, the client application can use the 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)
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.
For security reasons, authorization codes expire after 10 minutes. Their short-lived nature enhances security by limiting their potential for misuse if intercepted.
GET https://dashboard.commercelayer.io/oauth/authorize
client_id
String
Required
Your client ID (from you API credentials).
redirect_uri
String
Required
Your 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.
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:
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:
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.
POST https://auth.commercelayer.io/oauth/token
grant_type
String
Required
authorization_code
client_id
String
Required
Your client ID (from you API credentials).
client_secret
String
Required
Your client secret (from you API credentials).
redirect_uri
String
Required
Your redirect URI.
scope
String
Optional
Your access token scope (market, stock location).
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:
On success, the API responds with a 200 OK
status code, returning the requested access token and owner info, along with a :