REST API Authentication

Retail Digital Commerce REST APIs use OAuth 2.0 with bearer tokens for authentication.

This section applies to both OSF . This section applies to Open Storefront Framework .

The REST APIs support two authentication approaches:
  • To enable an external application such as an integration or server-side extension to be authenticated, the application must first be registered in the administration interface, as described in Register applications. As part of the registration process, an application key is generated. During authentication, the application key must be passed to Retail Digital Commerce using a POST request to the appropriate login endpoint.
  • To authenticate an internal user or storefront shopper, the user login and password must be passed to Retail Digital Commerce using a POST request to the appropriate login endpoint.
In either case, if the authentication succeeds, the endpoint returns an access token that must be supplied in subsequent requests. Note that application keys and access tokens are long base64-encoded strings.

Use the Application Key for Authentication

When you register an application, Retail Digital Commerce automatically generates a JSON Web Token called an application key. You send the application key in the authorization header of a POST request, and Retail Digital Commerce responds with an access token that the application must supply in subsequent requests.

Note:

Application keys should be stored securely and all requests that include them must be sent via HTTPS. They should be used by integrations and server-side extensions only, and should not be sent by a browser.

Send the authorization header in a POST request to the appropriate login endpoint:

  • Use POST /ccadmin/v1/login if your application makes calls to the Admin API endpoints on the administration server.
  • Use POST /ccapp/v1/login if your application makes calls to the Store Extension Admin endpoints on the storefront server.
  • Use POST /ccappagent/v1/login if your application makes calls to the Store Extension Agent endpoints on the storefront server.
The Content-Type header value must be set to application/x-www-form-urlencoded, and the body of the request must include the grant type client_credentials. For example: 
POST /ccapp/v1/login  HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer <application_key>

grant_type=client_credentials
The following example shows the server’s JSON response, which includes the access token: 
{
    "access_token": "<access_token>",
    "token_type": "bearer"
}
Now whenever the application needs to access a secured endpoint, it must issue a request with an authorization header that contains the access token. The following example shows an authorization header for a request that returns orders: 
GET /ccapp/v1/orders  HTTP/1.1
Authorization: Bearer <access_token>

Use Login Credentials for Authentication

When an individual user such as a shopper logs in, there is no application key, so the user login and password must be supplied in the body of the request. The following example illustrates logging into a shopper account on the storefront server:

POST /ccstore/v1/login  HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=johndoe@example.com&password=g4dEj3w1
The response includes an access token to use in subsequent requests. Each API you log into returns a separate access token. The following example shows the server’s JSON response, which includes the access token: 
{
    "access_token": "<access_token>",
    "token_type": "bearer"
}

Multi-factor authentication

Logging into the Admin API or Agent API as an internal user involves multi-factor authentication. For example, to log into the Admin API, you issue a POST request to the /ccadmin/v1/mfalogin endpoint, and include the username, password, and passcode in the body of the request. For example: 
POST /ccadmin/v1/mfalogin  HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=admin1@example.com&password=A3ddj3w2&totp_code=365214

To obtain passcodes, the login account must be registered with the Oracle Mobile Authenticator app. See Access the Retail Digital Commerce administration interface for more information.

Note that account passwords and passcodes may expire or be changed, so you must make sure you have up-to-date values when you log in.

Refresh an Access Token

Each access token expires automatically after a predetermined period of time. Tokens associated with an application key expire after 5 minutes. Tokens associated with user credentials expire after 15 minutes.

To avoid being logged out of an API, you can replace the current token by issuing a POST request to the API’s refresh endpoint. Include the current access token in the authorization header, just as you would for any other authenticated request. Retail Digital Commerce generates and returns a new token and restarts the clock. You then use the new token in the authorization headers of subsequent requests. Note that you may need to refresh the token multiple times (every 5 minutes for a login with an application key, every 15 minutes for a login with user credentials) if you need to remain logged in for an extended period of time.

The following example is an authorization header that refreshes an access token for the Admin API: 
POST /ccadmin/v1/refresh  HTTP/1.1
Authorization: Bearer <old_access_token>
The following example shows the body of the server’s response, which includes the new token: 
{
    "access_token": "<new_access_token>",
    "token_type": "bearer"
}

Change the token expiration period (Admin API only)

As mentioned above, the expiration period for tokens associated with user credentials is 15 minutes by default. For the Admin API, you can change the expiration period using the saveAdminConfiguration endpoint. For example, to change the period to 30 minutes: 
PUT /ccadmin/v1/merchant/adminConfiguration  HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{
    "sessionTimeout": 30
}

You can set sessionTimeout to any integer from 3 to 120. Note that the value you set also specifies the session timeout period for the administration interface, which is the period of inactivity after which the user is automatically logged out.

Access Preview through the APIs

You can use the Store API on the administration server to access your store in preview mode. This requires a multi-step authentication procedure.

First, log into the Admin API on the administration server using an account that has the Administrator role. Issue a POST request to the /ccadmin/v1/mfalogin endpoint, and include the username, password, and passcode in the body of the request. For example: 
POST /ccadmin/v1/mfalogin  HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=admin1@example.com&password=A3ddj3w2&totp_code=443589
The response returned includes an access token: 
{
    "token_type": "bearer",
    "access_token": "<access_token>"
}
Next, create a new preview user by issuing a POST request to /ccstore/v1/profiles on the administration server. (You can skip this step if you have previously created a preview user.) In the authorization header field of the request, pass in the access token that was returned by /ccadmin/v1/mfalogin: 
POST /ccstore/v1/profiles  HTTP/1.1
Authorization: Bearer <access_token>

In the body of the request, specify the values of the profile properties, as described in Create a shopper profile.

Now log in as the preview user by issuing a POST request to the /ccstore/v1/login endpoint on the administration server. Include the username and password in the body of the request. In addition, in the authorization header field of the request, pass in the access token that was returned by /ccadmin/v1/mfalogin: 
POST /ccstore/v1/login  HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=previewuser@example.com&password=Test1234
The response returned by /ccstore/v1/login includes a new access token: 
{
    "token_type": "bearer",
    "access_token": "<access_token_2>"
}

You can now make requests to the /ccstore/v1 endpoints on the administration server, passing in <access_token_2> (the access token that was returned by /ccstore/v1/login). You can also use the original access token (returned by /ccadmin/v1/mfalogin) to access /ccadmin/v1 endpoints and to create preview users with the /ccstore/v1/profiles endpoint.

Note that if your Retail Digital Commerce instance is running multiple sites, preview requires a specific site context. You can specify the site when you log in as a preview user and in subsequent calls to the Store API. If you do not specify a site, the default site is used. See Use the APIs on Instances Running Multiple Sites for more information about specifying the site in API calls.