Endpoints#

Every path below is relative to /api/v1. For request and response schemas, use the OpenAPI explorer or fetch /api/v1/openapi.json.

This table is maintained by hand and covers /api/v1 only. The generated contract — both surfaces, with schemas — is described in OpenAPI and client generation, which is also where to start if you would rather generate a client than write one.

"User only" means the route rejects service accounts with 403 A user session is required.

Operations#

Organizations#

Every organization route requires a user session.

GET /organizations accepts ?state=active|archived|all. Creating an organization makes you its owner. Archiving clears the caller's active organization.

Projects#

Creating a project also creates its three environments and the project-admin and member roles. GET /projects/{projectId} includes the environment list.

Service accounts#

The creation response contains data.apiKey exactly once.

Configuration#

Reading one value needs config:reveal for users but only config:read for service accounts. List responses always mask secrets.

RBAC#

POST /authorize takes projectId in the body, not the path.

Accounting#

Analytics requires both permissions. Usage replays return 200 with duplicate: true.

/analytics/activity returns daily active-subject, usage, and revenue trends — days is 7–90, default 30. /analytics/subjects is the paginated subject directory — days 7–365, plus q, sort, limit, and offset — and is the only list route that answers with { total, limit, offset, subjects } instead of a bare array. /subjects/{subjectId}/activity is one subject's series, meters, billing state, and 50 most recent events. All four accept an optional environmentId; the semantics are in Usage and billing.

Audit#

Latest 100 entries, newest first.

OIDC clients#

All three require a user session.

The creation response contains clientSecret once, and null for native clients.

Billing#

Checkout requires an idempotency-key header of 16–255 characters.

Subjects#

Deletes the Gate identity behind a subject id, along with its sessions, linked accounts, memberships, OAuth tokens and consents, and every role binding naming it. Billing and accounting rows are keyed on the opaque subject id and are deliberately kept.

Only a project the subject actually signed into may delete it: one of the caller project's OIDC clients must hold either a consent or a refresh token from that user, or the answer is 403. Both count, because a client marked skip_consent never writes a consent row. Without this rule, one project could delete an identity shared with every other Evonia product.

Webhooks#

Unauthenticated. Verified against the webhook secret stored for that environment.

Documentation#

/api/v1/docs is the Swagger UI, also reachable at /docs/api-reference.

Protocol routes#

These live under /api/auth, outside /api/v1, and are served by better-auth.