REST API authentication
Oracle Commerce REST APIs use OAuth 2.0 with bearer tokens for authentication.
- 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.