Important

We are updating the images for OroCommerce version 6.1 to align with the latest changes in the back-office design. During this transition, some images may still show older versions. Thank you for your patience as we work to update all visuals to reflect these changes.

Password Grant Type: Generate Token

To configure the authentication via the password grant type and retrieve the access token:

1. Provide your Request URL.

   The Request URL consists of your application URL and the /oauth2-token slug, e.g., https://yourapplication/oauth2-token

2. Specify the content-type in headers:

   Content-Type: application/json

3. Send a POST request with the following body parameters to the authorization server:

   • grant_type with the value password

   • client_id with the client identifier

   • client_secret with the client’s secret

   • username with the user’s username

   • password with the user’s password

4. Receive response from the authorization server with a JSON object containing the following properties:

   • token_type with the value Bearer

   • expires_in = 3600 seconds. Once the token is generated, it is valid for an hour and can be used multiple times within this time limit to request the necessary data. Expiration time can by configured in config/config.yml of your application

   • access_token a JSON web token signed with the authorization server’s private key

   • refresh_token a JSON web token used to request a new token when the access_token expires

5. Use the generated access token to make requests to the API.

Example

Request

POST /oauth2-token HTTP/1.1
Content-Type: application/json

Request Body

{
    "grant_type": "password",
    "client_id": "your client identifier",
    "client_secret": "your client secret",
    "username": "your user username",
    "password": "your user password"
}

Response Body

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "your access token",
    "refresh_token": "your refresh token"
}

The received access token can be used multiple times until it expires.

An example of an API request:

GET /api/users HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer your access token

According to Rfc6750, an access token can be included as a body parameter in requests.

Note

When sending the access token as a body parameter, the request must include a Content-Type header set to application/vnd.api+json.

Here is an example of how to send the access token as a body parameter:

POST /api/users HTTP/1.1
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json

{
    "access_token": "your_access_token",
    "data": {
      "type": "contacts",
      "attributes": {
        "firstName": "Jerry12",
        "lastName": "Coleman2"
      }
    }
}

Note

Access tokens for back-office and storefront API are not interchangeable. If you attempt to request data for the storefront API with a token generated for the back-office application, access will be denied.

Note

For the storefront API a customer user email address should be used as username.

Note

To get the access token for a visitor for the storefront API, use guest as username and password in the request to the authorization server. A new customer visitor is created for each created access token.

Note

When you need to transfer a visitor’s shopping list to a user, you must include the visitor’s access token in the access token generation request for that user. This visitor access token should be specified using the visitor_access_token parameter. For example:

POST /oauth2-token HTTP/1.1
Content-Type: application/json

{
    "grant_type": "password",
    "client_id": "your client identifier",
    "client_secret": "your client secret",
    "username": "your user username",
    "password": "your user password",
    "visitor_access_token": "visitor's access token"
}