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 API keys 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. GET /projects/{projectId} includes the environment list. Organization-level routes are for people only: an API key is refused even when it holds *.

API keys#

The creation response contains the raw key in data.secret exactly once.

Configuration#

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

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.

OAuth 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#

DELETE …/access removes one product's access: it cancels the subject's subscriptions, revokes this project's OAuth grants and entitlement grants, and blocks checkout. POST …/access restores it. Both are safe to repeat.

DELETE /projects/{projectId}/subjects/{subjectId} deletes the Gate identity behind a subject id, along with its sessions, linked accounts, memberships, and OAuth tokens and consents. 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.