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

# Integrations

> API keys let your chain's system register items and fire alerts with no one at the dashboard.

An **API key** lets your chain's system (ERP, online store, scheduling) do through the API what you do in the dashboard: register and update items, estimate the cost and send alerts, check the balance. The key identifies the system, not a person, and applies to the units you choose.

Only the chain **owner** sees **Integrations** in the menu and manages the keys.

## Create a key

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

Give it a **Name** to recognize the key later, such as "Downtown store ERP".

**2. Choose the units**

**All units, including future ones**, for the chain's central system, or **Selected units**, to open only some shops to a partner.

**3. Tick the permissions**

They are the same as the [team's](https://docs.needalert.app/en/establishments/team-and-roles.md), with three differences: every key reads the units it reaches; **Dispatch events** spends credits like a dispatch made from the dashboard; **Manage billing**, through the API, only reads the balance and the statement (buying stays in the dashboard).

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

**Token expiration**: no expiration, 30, 90, 180 or 365 days. An expired token stops working until you issue another one.

**5. Copy the token**

When you click **Create key**, the **Key token** dialog shows the token **only once**. Use **Copy token** and store it in the system that will call the API before clicking **Done**.

> [!WARNING]
>
> The token is like a password of your chain. Never put it in website code, app code or a message. If you lose it, issue a new token and revoke the old one.

## Edit a key

Under **View details**, **Edit** changes the name, the units and the permissions. The token stays the same: the system doesn't need an update.

## Rotate the token without downtime

A key can have **two active tokens** at the same time, so the rotation never leaves the system without access.

**1. Issue the new token**

In the key's details, **Issue token**. Copy it: it is also shown only once.

**2. Update the system**

Replace the token in the chain's system and check that it keeps working.

**3. Revoke the old one**

In the **Tokens** table, **Revoke token** on the old token. Whoever still used it loses access right away.

## Revoke a key

**Revoke key** turns off 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.

## Where the API shows in the dashboard

What the system does through the key appears in the dashboard with the **API** badge and the key's name: in the author column of [dispatches](https://docs.needalert.app/en/establishments/send-alerts.md), in the [credit statement](https://docs.needalert.app/en/establishments/credits.md) and under **Created by**, in the item's details. The credits spent are the same: 1 per person notified.

Items created through the API carry the **External reference (SKU)**, the item's code in the chain's system. You can also fill it in by hand, in the item form, so the system finds an item you registered in the dashboard.

> [card] [API documentation](https://docs.needalert.app/en/api/authentication.md)
>
> For whoever will build the integration: authentication, first request and the reference of every endpoint.


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