Authenticating API Calls

The Consystence API does not have a single login endpoint. Every request is authenticated per-request by a policy-scheme selector (MultiAuth) that inspects the credentials you send and routes them to the right validator. For an API consumer this reduces to three credentials you can present, distinguished by which header you set:

You are…	Credential	Header	Acquired via
A browser or interactive user	CIAM bearer token	Authorization: Bearer <token>	OIDC code+PKCE against id.consystence.com
A machine, script, or partner integration	Tenant API key (csk_…)	X-Api-Key: csk_…	POST /api/admin/api-keys
An offline site terminal	Site-PIN token (locally-issued JWT)	Authorization: Bearer <token>	Email + numeric PIN sign-in on the site server

This page is the practical “how do I authenticate my calls” guide. For the conceptual model — the MultiAuth selector, the oid-based identity, and the schemes that are deliberately absent — see Authentication. For the full key lifecycle (rotation, expiry, revocation), see API keys.

Where to call

All API traffic is cell-direct: you call https://{slug}.consystence.com (an org subdomain), which serves the server’s own admin and engineering API, including key management. The published OpenAPI reference documents the supported public (CLI-exposed) portion of this surface. There is no separate api.consystence.com host — see the public API surface.

The examples below use the org subdomain because that is where keys are minted.

Choosing a scheme

flowchart TD
    Q{Who is calling?} --> H[Interactive human in a browser]
    Q --> M[A machine / script / CI / partner]
    Q --> S[An on-site terminal that must work offline]
    H --> HB["CIAM Bearer<br/>Authorization: Bearer"]
    M --> MK["Tenant API key<br/>X-Api-Key: csk_…"]
    S --> SP["Site-PIN token<br/>Authorization: Bearer"]

The rule of thumb: humans authenticate as themselves with a CIAM token; machines authenticate as a tenant with an API key; an air-gapped site terminal uses a site-PIN. Do not drive the interactive OIDC flow from a headless service — mint an API key instead.

CIAM bearer tokens

The primary scheme for browsers and interactive users. Identity is issued by Entra External ID (CIAM) at id.consystence.com. Consystence is an OIDC relying party — it consumes the provider’s discovery document and JWKS to validate tokens; it does not issue them and does not serve an OIDC discovery document of its own.

A browser obtains a token through an OpenID Connect authorization-code flow with PKCE, which the server drives for you:

Method	Path	Purpose
GET	/auth/login	Builds the authorize URL from the IdP’s discovery document and redirects to id.consystence.com.
GET	/auth/callback	Validates state, exchanges the code (with the PKCE verifier) for tokens, establishes a server-side session.
POST	/auth/token	Returns the access token for the established session (POST, so the token never lands in a URL, log, or history).
POST	/auth/logout	Clears the session.

Once you hold an access token, send it on every request:

GET /api/sites HTTP/1.1
Host: acme.consystence.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

The receiving server validates the token locally (signature, issuer, audience, lifetime) against the configured authority — it does not call back to the identity provider on the request path. The token carries the stable membership key (the Entra oid); your Consystence role (owner / admin / member) is recomputed server-side from that oid and the request subdomain, not read from the token. See Roles & membership.

Note

There is no email/password login, no /register, and no /refresh, MFA, or password-reset endpoint for the CIAM identity — those belong to Entra External ID. If you need a non-interactive credential, use a tenant API key.

Tenant API keys (X-Api-Key)

Programmatic, CI, and partner integrations authenticate with a tenant API key. A key authenticates the tenant, not a person, and is scoped to the organisation that minted it.

Mint one with an admin credential:

POST /api/admin/api-keys HTTP/1.1
Host: acme.consystence.com
Authorization: Bearer <admin CIAM token>
Content-Type: application/json

{ "name": "ingest-pipeline", "role": "member", "expiresAt": "2027-06-29T00:00:00Z" }

The response returns the plaintext key exactly once — capture it immediately, as no later call re-emits it. Keys are prefixed csk_; only a short display prefix and metadata are retrievable afterwards.

Then send it in the X-Api-Key header (no Authorization header needed):

GET /api/sites HTTP/1.1
Host: acme.consystence.com
X-Api-Key: csk_xxxxxxxxxxxxxxxxxxxxxxxx

The key’s tenant and role come from the key record, so a key cannot act outside the organisation that issued it. Minting and revoking keys is an admin operation; the tenant is always derived from the authenticated caller, never from the request body.

Control-plane roles cannot be minted here

This tenant-facing endpoint rejects roles reserved for the account↔cell control plane. Those credentials are established only out-of-band at cell enrolment — you cannot self-mint a key that escalates beyond your tenant.

For rotation, expiry, listing, and revocation, see API keys.

Site-PIN (offline-capable)

Industrial sites — mining and CHPP plants — must keep operating when the upstream link is down. The LocallyIssuedJwt scheme exists for exactly this: a site-resident sign-in that does not depend on reaching Entra.

A site user signs in with email plus a numeric site PIN on the site server (POST /auth/site/login). On success the server issues a short-lived JWT signed by a local key (issuer consystence-local), validated against the server’s local JWKS endpoint. Sessions renew without re-entering the PIN via POST /auth/site/refresh — the CLI refreshes site-PIN sessions automatically. Because it is a bearer JWT, you send it in the same header as a CIAM token — the MultiAuth selector reads the token’s issuer to route it to the local validator:

GET /api/sites HTTP/1.1
Host: site.local
Authorization: Bearer <locally-issued JWT>

A site-PIN principal proves site presence, not organisation membership — it deliberately carries no oid and no org role, and confers no cloud or cross-tenant authority. It does carry a site role claim (owner / admin / member) that governs the site functions on that site: on a site server, managing site users, site configuration, and API keys are site functions authorised on that site role, so a site-PIN principal with an owner or admin site role qualifies.

Where this scheme is enabled

The site-PIN fallback is wired in on site-server topologies and non-production sandboxes (*.consystence.dev). Production cloud cells run the CIAM and API-key schemes only — a locally-issued token has no legitimate path to a cloud cell. For the exact sign-in flow see Authentication.

Sending the wrong combination

• Both X-Api-Key and Authorization — the server prefers the API key and logs a warning; it never rejects with 400 (HTTP clients commonly set both). Send only the credential you intend to use.
• No credential — the request fails closed with 401. Endpoints fail closed by default: a credential is required unless an endpoint explicitly opts out.
• An invalid or expired credential — a uniform 401. The server does not distinguish “unknown key” from “wrong key” in its response, by design.

A note on authority

Note

Authentication establishes who (or which tenant) is calling; it never grants authority to command field equipment. Control writes are gated independently, and platform AI is advisory-only — it configures, queries, classifies, and explains, but never issues control writes. Hard interlocks live in the IO modules and safety relays, below the API.

Control-plane authority

The account control plane (account.consystence.com) runs in production and provisions organisations onto the enrolled production cell; self-serve signup remains behind launch gates (operator tenant approval). The three credentials on this page — CIAM bearer, X-Api-Key, and site-PIN — are the authentication surface for the cell-direct API.

See also

• Authentication — the MultiAuth selector, oid-based identity, and the conceptual model
• API keys — minting, rotation, expiry, and revocation lifecycle
• Roles & membership — the owner / admin / member model
• API reference — the rendered OpenAPI for the supported public (CLI-exposed) surface
• Public API surface — why the API is cell-direct and there is no separate gateway host