Authentication & basics

The REST API is the full /api/v1 surface the product itself runs on, and this reference is generated from the running backend, so it cannot drift from the deployed API.

Authentication

Every request carries a bearer token. The requirement is the same for the whole API, so the operation pages do not repeat it:

Authorization: Bearer <token>

HTTP basic authentication is not supported. A token comes from one of two flows.

Session tokens

For a script or a service acting as a person, sign in and use the token that comes back:

POST /api/v1/auth/login
Content-Type: application/json

{ "email": "you@example.com", "password": "…", "tenantId": "optional" }

The response carries bearerToken and the session it belongs to. tenantId is optional: without it the session opens in your home tenant. POST /api/v1/auth/refresh returns a fresh token for a live session, POST /api/v1/auth/logout ends it, and GET /api/v1/auth/sessions lists the sessions you hold.

Sign-in is password-based only where the tenant allows it. A tenant federating its identity through SSO authenticates in the browser instead, and the resulting session token is what an API caller then uses.

OAuth 2.1 grants

For an application or an agent acting on someone’s behalf, Avera is an OAuth 2.1 authorization server with PKCE and dynamic client registration. Clients discover the endpoints rather than hard-coding them:

GET /.well-known/oauth-authorization-server

The flow is the standard one: register (or use a pre-registered client_id), send the user to the authorization endpoint, let them sign in and approve the tenant, the projects and the scopes, then exchange the code at POST /oauth2/token with the PKCE verifier. Tokens rotate, POST /oauth2/revoke revokes them, and a grant never exceeds the live access of the person who approved it: when their access changes, the connection’s reach changes with it on the next request.

Scopes are read, propose and generate. A grant with propose does not write directly: its changes land as proposals a named human accepts in Avera. MCP clients use exactly this flow, and the MCP guide covers the connector setup for Claude, ChatGPT and your own agents.

Which flow to use

A tenant that federates its identity through SSO has no password to send, so POST /api/v1/auth/login is refused for its people: the OAuth flow is the one that works everywhere, because its sign-in step federates to your identity provider like any other login.

For an unattended integration, the supported grant types are authorization_code and refresh_token. There is no client credentials grant and no API key, so an integration acts on behalf of a person: someone approves the grant once, and the integration holds a refresh token that rotates. That grant is bounded by the approver’s live access, which is what makes it safe, and also what ends it when they leave. For a team-owned integration, approve it with an account the team owns rather than a personal one.

Request context

• Tenant: a session is scoped to one tenant. X-Tenant-ID selects another tenant you participate in; the header alone grants nothing, the participation does.
• Project and branch: domain reads and writes carry their project and branch, usually in the path or as query parameters. A read resolves through the branch’s lineage, so the same call on two branches legitimately returns different content.

Writes

Mutations follow the product’s own rules: lifecycles, permissions, validation and audit apply to API callers exactly as they apply in the browser. A write built on a stale read is rejected rather than silently overwriting, and nothing an integration does escapes the record.