# Headless API Authentication

## 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

```bash
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.

{% hint style="warning" %}
The code expires after 1 minute. A new code must be requested if it has not been exchanged for a token.
{% endhint %}

{% hint style="info" %}
The `code` is URL encoded. The code will need to be [URL-decoded](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding) before the next step. Some web frameworks might do that automatically.
{% endhint %}

## Exchange code for a token

```bash
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>"
        }'
```

{% hint style="danger" %}
The authorization header above must be formatted. You can find an explanation and examples here: [Token endpoint - Authorization Header](/readme/headless/headless-api-authentication/token-endpoint-authorization-header.md)
{% endhint %}

An example of an expected response:

```json
{
  "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.&#x20;


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dev.ucommerce.net/readme/headless/headless-api-authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.