REST API authentication
Oracle Commerce REST APIs use OAuth 2.0 with bearer tokens for authentication.
This section applies to Open Storefront Framework (OSF) and Storefront Classic.
- 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 Oracle 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 Oracle Commerce using a
POST
request to the appropriate login endpoint.
Use the application key for authentication
When you register an application, Oracle 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 Oracle 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.
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
{
"access_token": "<access_token>",
"token_type": "bearer"
}
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
{
"access_token": "<access_token>",
"token_type": "bearer"
}
Multi-factor authentication
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 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. Oracle 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.
POST /ccadmin/v1/refresh HTTP/1.1
Authorization: Bearer <old_access_token>
{
"access_token": "<new_access_token>",
"token_type": "bearer"
}
Change the token expiration period (Admin API only)
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.
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
{
"token_type": "bearer",
"access_token": "<access_token>"
}
/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.
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
/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 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 information about specifying the site in API calls.