Authentication

Oracle Commerce Cloud Service REST APIs use OAuth 2.0 with bearer tokens for authentication. Two authentication approaches are supported:

• To enable a third-party application to be authenticated, the application must first be registered. As part of the registration process, an application key is generated. During authentication, the application key must be passed to Oracle Commerce Cloud Service using a POST request to the appropriate login endpoint.
• To authenticate an administrator or storefront shopper, the user login and password must be passed to Oracle Commerce Cloud Service 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, Oracle Commerce Cloud Service 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 Cloud Service 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.

Send the authorization header in a POST request to the appropriate login endpoint. 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 /ccadmin/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 /ccadmin/v1/orders HTTP/1.1
        Authorization: Bearer <access_token>
      

Use login credentials for authentication

When you log in as an individual user (either a shopper or an internal user such as admin), there is no application key, so you must instead supply the user login and password in the body of the request. The following example illustrates logging in as a shopper on the storefront server:

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

        grant_type=password&username=[e-mail]&password=g4dEj3w1
      

The following example shows the server's JSON response, which includes the access token to be used in subsequent requests:

        {
          "access_token":"<access_token>>,
          "token_type":"bearer"
        }
      

Refresh an access token

By default, each access token expires automatically after 15 minutes. To avoid being logged out automatically, you can replace the current token by issuing a POST request to the appropriate refresh endpoint. Include the current access token in the authorization header, just as you would for any other authenticated request. Oracle Commerce Cloud Service 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 (once every 15 minutes) 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"
        }
      

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/login endpoint, and include the username and password in the body of the request. For example:

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

      grant_type=password&username=[e-mail]&password=A3ddj3w
    

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. (Note that 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/login:

      {
        POST /ccstore/v1/profiles HTTP/1.1
        Authorization: Bearer <access_token>
      }
    

In the body of the request, specify the values of the profile properties.

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/login:

    
      POST /ccstore/v1/login HTTP/1.1
      Authorization: Bearer <access_token>
      Content-Type: application/x-www-form-urlencoded

      grant_type=password&username=[e-mail]&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/login) to access /ccadmin/v1 endpoints and to create preview users with the /ccstore/v1/profiles endpoint.

Note that if your Commerce Cloud instance is running multiple sites, preview requires a specific site context. You can use the x-ccsite header to 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.