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

# Authentication

> Service-account tokens, sandboxes and API versioning

The S2S API authenticates with your project's **service-account token** as a Bearer credential:

```
Authorization: Bearer <service account token>
```

## Creating a token (self-serve)

1. In the Gleap dashboard, open your project (or create a new one — see [Sandbox](#sandbox) below).
2. Go to **Project Settings → API Token**.
3. Create a **service account** and copy its token.

Tokens are managed on that same page: create additional ones, or delete an account to revoke its token — revocation applies within milliseconds.

<Warning>
  The **"API key"** and **"Secret API key"** from the widget/SDK setup pages are different credentials and will return `401` on `/v3/s2s/*`. Only the service-account token from **Project Settings → API Token** works here.
</Warning>

## Sandbox

There are no special test credentials: your sandbox is simply a **separate Gleap project** with its own service-account token. Create a fresh project, configure your workflows and AI agents in it the way you plan to in production, and integrate against it. When you go live, switch the token (and any workflow ids) to your production project's values.

## Scoping

A token is scoped to its project. It can only read and write that project's contacts and conversations, only subscribe to that project's event stream, and only manage that project's webhooks. Requests addressing anything else return `404`.

## API versioning

Pin the API version on every request (recommended):

```
Gleap-Version: 2026-08-01
```

Without the header you get the current version. Within a version we only make **additive** changes — new fields, new event types, new optional parameters — and your integration must ignore fields it does not know. Breaking changes ship as a new dated version; the previous version stays supported for at least 12 months. Every response echoes the resolved version in a `Gleap-Version` header.

## Rate limits

| Limit                                     | Scope            |
| ----------------------------------------- | ---------------- |
| 600 requests / minute (plus short bursts) | per token        |
| 60 messages / minute                      | per conversation |
| 20 uploads / minute                       | per token        |

Exceeding a limit returns `429` with a `Retry-After` header (seconds). Honor it — retries before it elapses count against the same budget.