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

# Authentication

> How to authenticate requests to the Fire API and verify incoming webhook events.

Fire uses two mechanisms for authentication: a login flow to obtain a Bearer token for API calls, and a signature-based mechanism to verify incoming webhook events.

## Environments

| Environment    | Base URL                    |
| -------------- | --------------------------- |
| **Staging**    | `https://stg.api.fire.rest` |
| **Production** | `https://api.fire.rest`     |

Start your integration against **staging** — it mirrors production but is isolated from live data.

## API authentication

<Note>
  The auth model depends on which endpoint family you call:

  * **`/api/v1/*` endpoints** (orders, cancel-order, cash-management, fiscal-callback, fiscal-print, channels-config, payment-methods-config) — only `x-api-key: pk_live_...` is required. **Skip the login flow below.**
  * **`/api/v4/integrations/sales/aggregator/*` endpoints (legacy)** — use the OAuth login flow described in this page to obtain a Bearer access token.
</Note>

Calling the Fire API requires four headers on every request:

| Header             | Value                        |
| ------------------ | ---------------------------- |
| `x-api-key`        | Your Fire API key            |
| `x-client-channel` | `integration`                |
| `account`          | Your Fire account identifier |
| `Authorization`    | `Bearer <accessToken>`       |

The `x-api-key` identifies your integration. The `x-client-channel` header tells Fire the request comes from an external integration. The `account` header identifies which Fire account the request targets. The Bearer token proves your session is authenticated — you obtain it by calling the login endpoint.

### Step 1 — Get an access token

Call [`POST /api/authentication/login`](/en/api-reference/login) with the headers above and your client credentials in the body, using the `client_credentials` grant type:

```http theme={null}
POST https://stg.api.fire.rest/api/authentication/login
x-api-key: <your_api_key>
x-client-channel: integration
account: <your_account_id>
Content-Type: application/json

{
  "client_id": "<your_client_id>",
  "client_secret": "<your_client_secret>",
  "grant_type": "client_credentials"
}
```

A successful call returns `201 Created` with the access token:

```json theme={null}
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### Step 2 — Use the token in every request

Include all four headers in subsequent API calls:

```http theme={null}
POST https://stg.api.fire.rest/api/v4/integrations/sales/aggregator/orders
x-api-key: <your_api_key>
x-client-channel: integration
account: <your_account_id>
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
```

<Note>
  Re-authenticate before the token expires to avoid `401` errors on in-flight requests.
</Note>

### Where to get your credentials

API keys, client credentials, and account identifiers are managed from the Fire dashboard under **Settings → API Keys**. Contact your Fire account team if you do not have access.

## Webhook signature verification

Every event Fire sends is signed so your system can confirm it genuinely came from Fire and was not tampered with in transit.

### How it works

When you register your endpoint in the Fire dashboard, Fire generates a **webhook secret** — a random string that only you and Fire know. It never travels in any request.

Each time Fire sends an event, it uses that secret to compute a signature of the request body and attaches it as the `X-Fire-Signature` header. Your system does the same calculation on the body it receives and compares the result:

```
Fire:         secret + body  →  signature  →  sends in X-Fire-Signature header
Your system:  secret + body received  →  recompute  →  compare
```

If the signatures match, the request is authentic. If they don't, discard it.

<Warning>
  Always verify the signature before processing an event. Skipping this step exposes your endpoint to spoofed requests from anyone who knows your URL.
</Warning>

### Setup

When you add a webhook endpoint under an [aggregator integration](/en/configuration/backoffice-integrations), the dashboard shows the signing secret for that endpoint (often only once). Copy it and store it securely — you need it to verify every delivery.

### Verification steps

<Steps>
  <Step title="Read the signature header">
    Extract the value from the `X-Fire-Signature` header on the incoming request.
  </Step>

  <Step title="Recompute the signature">
    Using your webhook secret, compute HMAC-SHA256 of the **raw request body** (before any JSON parsing).
  </Step>

  <Step title="Compare">
    Compare the computed value with the header value using a constant-time comparison. If they match, process the event. If not, return `400` and discard it.
  </Step>
</Steps>

```js theme={null}
const crypto = require("crypto");

function verifySignature(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}
```

<Note>
  Use the **raw body bytes** for the HMAC computation — not a parsed or re-serialized version of the JSON. Parsing and re-serializing can alter whitespace or key ordering and cause valid signatures to fail verification.
</Note>