Authentication

Every route under /api/v1 wants an Authorization: Bearer <token> header. What differs is where the token came from, and that depends on who is calling.

If you are writing a script, a CI job or a service, you want the first row and can skip the rest.

The machine flow, in one request

Tokens are issued per zone, by the zone you are calling, so the host below is the zone you intend to work in and not a shared login service.

curl -s https://api.eu-par-1.interlaken.ai/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials

Credentials go in an HTTP Basic header, which OAuth calls client_secret_basic. If your HTTP client makes that awkward, put client_id and client_secret in the form body instead: both are accepted.

There is no refresh token on this grant. When the hour is up, ask for another token.

The browser flow, in outline

A third-party application that acts on a person's behalf runs the authorization code flow. PKCE is mandatory, codes live 90 seconds, and the endpoints are advertised at /.well-known/oauth-authorization-server so a compliant client can discover them rather than being configured.

Scopes shape the result. Asking for openid adds an id_token and makes /oauth/userinfo answer with claims. Asking for mcp unlocks the Model Context Protocol server, which is how coding agents talk to the platform.

What a token carries

An access token is a signed JWT. You do not have to open it, but if you do, the claims that matter are the tenant, the role and the scope, plus a typ claim naming the kind of principal: a token minted for an API client says api_client, and one minted for a VM's metadata service says instance. Tokens from the OAuth server are signed with RS256 and can be verified against the published key set. Verifying a token covers that.

Revocation is immediate

Revoking a token is not a matter of waiting for it to expire. Every zone consults a revocation list on each request, so a rotated secret, a deleted client or an explicit POST /oauth/revoke takes effect on the next call. Rotating an API client's secret kills the old one at once, with no grace period, so deploy the new secret before you rotate.