Skip to main content
The Observe API gives programmatic access to the same data as the management console. The Observe CLI is built on it, so every CLI command has an API equivalent.

​
1. Base URL and authentication

Every request authenticates with an API key as a bearer token. The key determines the project, so requests carry no project ID.

​
2. API keys

Create keys in the console under Observe → Settings → API keys.
  • Permissions: each key lists the permissions it grants. Choose read permissions for analysis and exports. Add write permissions only where an integration sends data, for example server-side enrichment.
  • IP restriction: limit a key to specific IP addresses or CIDR ranges. Without a restriction, the key works from any address.
  • Expiry: keys can expire after 7, 30 or 90 days or remain valid until revoked. Personal keys expire after at most 90 days.
  • Who can create keys: project owners create project keys. Other project members can create personal keys with read permissions.

​
3. Endpoint groups

All paths are relative to https://api.cloud.corbado.io/v1. Endpoints under /observe/dataContext/ serve interactive investigation in the CLI and have no compatibility guarantee. Build integrations on the endpoint groups above.

​
4. Paging and limits

  • Paging: list endpoints return the headers X-Corbado-Page, X-Corbado-TotalPages and X-Corbado-TotalItems.
  • Busy responses: time-series and funnel reads can return 429 Too Many Requests with a Retry-After header when the service is busy. Retry after the indicated delay.
  • Export concurrency: a project can run two time-series exports at the same time. Further requests return 429 until one completes.

​
5. Server-side enrichment

Some facts about a journey exist only on your servers, for example the user a login resolved to or a risk or bot verdict. Send them with POST /observe/events and a key that has the events write permission. An enrichment event attaches a user reference or tags to a flow. It targets the flow either by the ID of an event Observe already received or by a time-based match within 10 seconds. One request carries up to 2,000 events. Enrichment arrives through an authenticated server-to-server call, so values that should not travel through the browser stay on your side.

Observe CLI

The same API from a terminal or an AI agent.

Exports

Download daily tables and KPI series.