Authentication

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

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

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.

Tick the permissions

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

Set the token expiration, if you want

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

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.

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:

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.

Issue the new token

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

Update your system

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

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.

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.

Introduction

Guides

Conventions

Endpoints

Create the key

Use the token

What each response means

Rotate the token without downtime

Revoke the key

​Create the key

​Use the token

​What each response means

​Rotate the token without downtime

​Revoke the key

Create the key

Use the token

What each response means

Rotate the token without downtime

Revoke the key