Skip to main content
The S2S API authenticates with your project’s service-account token as a Bearer credential:

​
Creating a token (self-serve)

  1. In the Gleap dashboard, open your project (or create a new one — see 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.
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.

​
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):
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

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