# Authentication

All Limio APIs use **OAuth Bearer Tokens** for authentication. This is the standard method for every integration — server-to-server, front-end, and third-party.

{% hint style="info" %}
For the full API reference, see [docs.limio.com/api](https://docs.limio.com/api).
{% endhint %}

## OAuth Bearer Token

The client credentials method generates an OAuth Bearer Token for secure, server-to-server authentication without user involvement. It gives full read/write access to all Limio APIs, including Orders, Subscriptions, Catalog, Abandoned Basket, External Identities, and more.

### Prerequisites

You need a `client_id` and `client_secret`. Contact [Limio Support](mailto:support@limio.com?subject=Request%20for%20Client%20ID%20and%20Client%20Secret\&body=Please%20provide%20my%20Client%20ID%20and%20Client%20Secret%20to%20access%20Limio's%20API%20via%20the%20bearer%20token.%20My%20Limio%20Commerce%20application%20is%20https%3A%2F%2F%7B%7Btenant%7D%7D.prod-us.limio.com.) to obtain these credentials.

### Get your Bearer Token

**Endpoint:**

```
POST {{tenant}}/oauth2/token
```

Where **{{tenant}}** is your Limio application URL:

* US hosting: `https://{{tenant}}.prod-us.limio.com`
* EU hosting: `https://{{tenant}}.prod.limio.com`

**Headers:**

| Header       | Value                               |
| ------------ | ----------------------------------- |
| Content-Type | `application/x-www-form-urlencoded` |

**Request body:**

| Parameter      | Value                                   |
| -------------- | --------------------------------------- |
| grant\_type    | `client_credentials`                    |
| client\_id     | Your `client_id` from Limio Support     |
| client\_secret | Your `client_secret` from Limio Support |

**Example request:**

```bash
curl --request POST \
  --url https://{tenant}/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id={client_id_details} \
  --data client_secret={client_secret_details}
```

**Response:**

```json
{
    "access_token": "<YOUR_TOKEN_HERE>",
    "token_type": "Bearer",
    "expires_in": 3600
}
```

### Use the token

Include the token in the `Authorization` header of every API request:

```javascript
const basePath = 'api';
const domain = 'prod.limio.com'; // or 'prod-us.limio.com'
const tenant = 'your-tenant';
const resp = await fetch(
  `https://${tenant}.${domain}/${basePath}/order`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: 'Bearer <YOUR_TOKEN_HERE>'
    },
    body: JSON.stringify({ /* order payload */ })
  }
);
```

***

## API Keys (legacy)

{% hint style="warning" %}
Some [Catalog API endpoints](https://docs.limio.com/api/catalog-api/catalog) accept a publishable API key for **read-only** access. However, Limio is in the process of moving all endpoints to OAuth Bearer Token — newer endpoints such as [get-offers-v2](https://docs.limio.com/api/catalog-api/catalog#get-offers-v2) and [get-add-ons](https://docs.limio.com/api/catalog-api/catalog#get-add-ons) already require OAuth. If you are planning a new integration and need to use a publishable API key, please [contact Limio](mailto:support@limio.com).
{% endhint %}

API keys are intended for headless or public-facing integrations where you only need to pull catalog data (campaigns, offers, products, pages). They are safe to embed in client-side code because they grant read-only access.

### Generate an API key

Log in to your Limio account, go to **Profile > Developers > Limio Keys** and click **Generate New**. Each account is limited to **2** API keys.

### Use the key

Pass the key directly in the `Authorization` header (no `Bearer` prefix):

```javascript
fetch('/api/catalog', {
  headers: { Authorization: 'YOUR_API_KEY_HERE' }
}).then(res => res.json());
```

### Delete a key

Select **Delete** next to the key in the developer area.

{% hint style="danger" %}
Deleting a key **cannot be undone**. Any application using that key will lose access immediately.
{% endhint %}


---

# 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://docs.limio.com/developers/api-documentation/authentication-overview.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.