REST API authentication
- To enable an external application to be authenticated, the application must first be registered in the administration interface. 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.
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 storefront server. - Use
POST /ccappagent/v1/login
if your application makes calls to the Store Extension Agent endpoints on 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
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
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.
{
"access_token":"<access_token>",
"token_type":"bearer"
}
/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=admin@example.com&password=A3ddj3w2&totp_code=365214
To obtain passcodes, the login account must be registered with the Oracle Mobile Authenticator app.
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>
The following example shows the body of the server's response, which includes the new token:
{
"access_token": "<new_access_token>",
"token_type":"bearer"
}
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.
/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.
/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 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.