Headless API Authentication

Quick start guide - Authenticating a client

Obtaining Credentials

1. Navigate to the Ucommerce Backoffice (/ucommerce) as an administrator.

2. In the Settings menu, click API Access.

3. When having multiple stores, one must be selected in the top-right corner dropdown.

4. Take note of the Client ID and the matching Secret.

5. Add the URL of your client to the URL Whitelist.

The headless API uses OAuth2 for authentication. This involves 2 steps: getting an authentication code and exchanging the code for a token.

Connect

curl -D- -G \
    <base_url>/api/v1/oauth/connect \
    -d client_id=<CLIENT_ID> \
    -d redirect_uri=<REDIRECT_URI> \
    -d response_type=code

• redirect_uri is where you will be redirected to after the call has finished. This needs to match a redirect URL specified in the URL Whitelist.

The expected response is a 302 (Found or Moved Temporarily).

The location header contains the authentication code. This will be used in the next step.

The code expires after 1 minute. A new code must be requested if it has not been exchanged for a token.

The code is URL encoded. The code will need to be URL-decoded before the next step. Some web frameworks might do that automatically.

Exchange code for a token

curl -D- -X POST <base_url>/api/v1/oauth/token \
    -u <CLIENT_ID>:<CLIENT_SECRET> \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d '{
            "grant_type" : "authorization_code"
            "code": "<CODE>"
            "redirect_uri" : "<REDIRECT_URL>"
        }'

The authorization header above must be formatted. You can find an explanation and examples here: Token endpoint - Authorization Header

An example of an expected response:

{
  "access_token": "eyJhbGciOiJIUzI1Ni978juanR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJmYTE4OTI3MS1mOTY1LTRmNWMtOTlmOS1lNDViNzNiYzI4MzkiLCJjbGllbnRJZCI6InZpaWEtZnBwIiwicm9sZSI6IkNsaWVudFVzZXIiLCJzZ67623aW9uSWQiOiJlZmE1NWU0ZS0xZTUxLTQ1YWMtYWEyYy01OThhNjFjMTZlOTYiLCJuYmYiOjE1Njc0MTQxNzMsImV4cCI6MTU2NzQxNzc3MywiaWF0IjoxNTY3NDE0MTczfQ.7QD6zGcdonYy79384buXOqsykWrbWa3L6LW4d9uzb-zA",
  "expires_in": 300,
  "redirect_uri": "https://httpbin.org/anything",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI687234pXVCJ9.eyJ1c2VySWQiOiJmYTE4OTI3MS1mOTY1LTRmNWMtOTlmOS1lNDViNzNiYzI4MzkiLCJjbGllbnRJZCI6InZpaWEtZnBwIiwiY29uc2VudElkIjoiYTYyODExYWYtNzUxMS00ZWQ0LoyiauasiYTEtMjAwNzc2NGQ1MTIwIiwic2Vzc2lvbklkIjoiZWZhNTVlNGUtMWU1MS00NWFjLWFhMmMtNTk4YTYxYzE2ZTk2Iiwicm9sZSI6IlJlZnJlc2hUb2tlbiIsIm5iZiI6MTU2NzQxNDE3MywiZXhwIjoxNTY4NjIzNzczLCJpYXQiOjE1Njc0MTQxNzN9.5-x0NNg5lMxPnZRYtu983764q0sbPcSb7U9b23e3Zwx0Ss9I",
  "token_type": "bearer"
}

• access_token will be used in all future requests.

• expires_in can be used to identify when to refresh the token.

• refresh_token will be used to refresh an expired or expiring token.

Using the token

All subsequent requests to the Headless API require the access_token in their respective Authorization headers.