API guide

Authentication

Overview

OrdinateDB accepts human sessions and bearer service tokens. Start with GET /v1/auth/methods: it is anonymous and returns the server posture (disabled, shadow, or enforced) plus the configured human login methods (local and/or oidc).

Use a human session for an interactive browser and a service token for unattended software. A custom collector can instead use its service token or a matched mTLS certificate.

Quick example

Ask the server which authentication posture and human login methods it has configured before showing a sign-in flow.

cURL

curl "$ORDINATE_URL/v1/auth/methods"

Documented response shape

{
  "auth_mode": "enforced",
  "login_methods": ["local", "oidc"]
}

Do not infer provider details from this response. It deliberately exposes only the bounded information a login screen or client needs.

How it works

Local human login

POST /v1/auth/login/local accepts a username and password. Success is 204 No Content and sets an HttpOnly ordinate_session cookie. A browser will retain that cookie when the request uses credentials: "include". cURL needs a cookie jar.

cURL session

curl --request POST \
  --url "$ORDINATE_URL/v1/auth/login/local" \
  --header "Content-Type: application/json" \
  --cookie-jar ordinate.cookies \
  --data '{"username":"engineer","password":"replace-me"}'

curl --url "$ORDINATE_URL/v1/auth/whoami" \
  --cookie ordinate.cookies

Browser JavaScript

await fetch(`${ordinateUrl}/v1/auth/login/local`, {
  method: "POST",
  credentials: "include",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ username, password })
});

const me = await fetch(`${ordinateUrl}/v1/auth/whoami`, {
  credentials: "include"
}).then((response) => response.json());

Invalid credentials return 401 without disclosing whether the username exists. A sealed account returns 403. Model-less configurations return 503.

OIDC human login

When discovery includes oidc, navigate the browser to GET /v1/auth/login. The server starts the authorization-code flow, validates the callback at GET /v1/auth/callback, sets the same HttpOnly session cookie, and redirects back to the portal. These are browser redirects, not JSON token endpoints.

Bearer service tokens

Automation should use a service identity. An administrator creates the identity with POST /v1/auth/service-identities, then mints a token with POST /v1/auth/service-identities/{id}/tokens. The plaintext token appears exactly once in the 201response and cannot be retrieved later.

Create and use a service token

curl --request POST \
  --url "$ORDINATE_URL/v1/auth/service-identities" \
  --header "Authorization: Bearer $ADMIN_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"kind":"integration","name":"energy-report"}'

curl --request POST \
  --url "$ORDINATE_URL/v1/auth/service-identities/$SERVICE_ID/tokens" \
  --header "Authorization: Bearer $ADMIN_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"expires_at_ns":1785067200000000000,"comment":"reporting job"}'

curl "$ORDINATE_URL/v1/auth/whoami" \
  --header "Authorization: Bearer $ORDINATE_TOKEN"

Every subsequent request sends Authorization: Bearer $ORDINATE_TOKEN. Tokens are allow-only: the associated principal’s roles and grants determine the effective capabilities and resource scopes. An unknown future capability string must not be treated as permission by an older client.

Common patterns

Authenticate a collector

gRPC collectors may authenticate with a bearer service token or an mTLS client certificate. For bearer authentication, the collector’s collector_id must exactly match the authenticated service identity name. With mTLS, a URI or DNS SAN is matched to a kind=collector identity. See the gRPC ingest guide.

Reference

Inspect and end sessions

GET /v1/auth/whoami returns the resolved principal, roles, capabilities, authorization snapshot, mode, and session expiry.
GET /v1/auth/sessions lists the caller’s human sessions;?all=true requires admin.
POST /v1/auth/logout revokes the current session and clears its cookie.
DELETE /v1/auth/sessions/{id} is the administrator path for revoking another session.
POST /v1/auth/service-identities/tokens/{token_id}/revokerevokes a service token.

Exact request and response schemas are in the REST endpoint reference.