> ## Documentation Index
> Fetch the complete documentation index at: https://docs.needalert.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Create an API key in the dashboard and send its token on every request.

Every API request carries an **API key** of your chain. The key is created by the chain **owner** in the dashboard, on the **Integrations** screen, and identifies the system calling the API (an ERP, an online store, a scheduling system), not a person.

## Create the key

**1. Open Integrations and click New key**

Only the chain owner sees **Integrations** in the menu. Give it a **Name** that identifies the system, such as "Downtown store ERP".

**2. Choose the units**

**All units, including future ones**, for the chain's central system, or **Selected units**, for a partner that serves only some shops. A unit outside the list doesn't exist for the key: the API answers **404**.

**3. Tick the permissions**

Every key has `view`. The others follow the dashboard permissions (see the table below).

**4. Set the token expiration, if you want**

**Token expiration** is optional. An expired token answers **401** until you issue another one.

**5. Copy the token**

When you click **Create key**, the **Key token** dialog shows the token **only once**. Copy it into your system's secret store before clicking **Done**. If you lose it, issue a new token and revoke the old one.

| Permission | What it allows in the API |
| - | - |
| `view` | Read units, items, subscriber counts and dispatches. Every key has it. |
| `create_items` | Create items. |
| `edit_items` | Edit, archive and change the picture of items. |
| `dispatch_events` | Preview, send, schedule, reschedule and cancel alerts. Spends credits like a dispatch made from the dashboard. |
| `manage_billing` | Read the credit balance and statement. Buying credits stays in the dashboard. |

> [!WARNING]
>
> The token is a server secret. Never put it in browser code, app code or a repository. Whoever holds the token acts for your chain in the key's units.

## Use the token

Send the token in the `Authorization` header of every request, and ask for JSON in `Accept`:

```bash theme={null}
export API=https://needalert.app/api/v1
export TOKEN='3|na_...'

curl "$API/establishments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

The token has the form `<id>|na_...`. Send it whole, including the vertical bar.

## What each response means

| HTTP | `code` | Cause |
| - | - | - |
| 401 | `unauthenticated` | Token missing, malformed, expired or revoked. |
| 403 | `forbidden` | The key lacks the permission this operation needs in this unit. |
| 403 | `tenant_suspended` | The chain that owns the key is suspended. |
| 403 | `establishment_unavailable` | The unit is inactive or suspended. |
| 404 | `not_found` | The resource doesn't exist or is outside the key's units. The API never reveals whether a resource you cannot see exists. |

## Rotate the token without downtime

A key accepts up to **two active tokens** at the same time, so the rotation has no window without access.

**1. Issue the new token**

In **Integrations**, open the key (**View details**) and click **Issue token**. Copy it: it is also shown only once.

**2. Update your system**

Replace the token in your secret store and confirm the calls still answer **200**.

**3. Revoke the old token**

In the **Tokens** table, use **Revoke token** on the old one. A system still using it loses access right away.

## Revoke the key

**Revoke key** disables every token of the key right away. The key stays in the list as **Revoked**, for history, and cannot be reactivated: create another one.

> [!NOTE]
>
> **Last used** shows the most recent call among the key's active tokens. A revoked token's use no longer counts, and a newly issued token only shows up after its first call.

See also the dashboard page: [Integrations](https://docs.needalert.app/en/establishments/integrations.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.