Authenticating API Calls

The Consystence API does not have a single login endpoint. The server authenticates each request on its own, routing the credential it carries 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 that reads data	Tenant API key (csk_…), read-only by default	X-Api-Key: csk_…	POST /api/admin/api-keys or csy api-key create
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 — how the server tells the credentials apart, the oid-based identity, and the account flows that belong to the identity provider — see Authentication. For the full key lifecycle (classes, 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 endpoints the CLI and its client library call, key management included. 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 that reads data]
    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 that read data authenticate as a tenant with an API key; an air-gapped site terminal uses a site-PIN. API keys are read-only by default: a read-only key reads tenant and site data and never changes anything. To make a change, sign in as a person. The one exception is an operator key, which acts for one named person on one site to run that site’s device commands and acknowledge its alarms. Do not drive the interactive OIDC flow from a headless service; for read access, mint an API key instead.

CIAM bearer tokens

The credential 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 to read data, use a tenant API key.

Tenant API keys (X-Api-Key)

Programmatic, CI, and partner integrations that read data authenticate with a tenant API key. Keys are read-only by default; see API keys. A read-only key authenticates the tenant, not a person, and is scoped to the organisation that minted it; an operator key also names the person it acts for.

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": "ci-site-reader", "role": "admin", "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, class and role come from the key record, so a key cannot act outside the organisation that issued it. Minting, listing and revoking keys is an admin operation for a signed-in person, never for an API key; the tenant is always derived from the authenticated caller, never from the request body.

A key’s role is limited

A read-only key carries member or admin, never owner and never a role above that of the person who creates it; any other role is refused. The role only decides which reads the key may make.

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. Site-PIN sign-in 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 server 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 token carries the user’s site role and no organisation claims (no oid, no org role), and a production cloud cell does not accept it (see the note below). The site role governs the site functions on that site. On a site server, the Owner, Admin and Site admin site roles administer the site: site users, site configuration and API keys. A Site admin cannot grant a role above its own and cannot create API keys (it can list and revoke them). A site-PIN Owner or Admin creates member keys only. The full list of site roles is under Site roles on a site server.

Where this scheme is enabled

The site-PIN scheme is enabled on site servers. Every hosted tenant, on consystence.com or consystence.dev and sandboxes included, is served by the production cloud service, which runs the CIAM and API-key schemes only and does not accept site-PIN tokens. 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 key) is calling; on its own it never grants authority to command equipment. Commands are gated independently, by the caller’s command authority and the site’s command policy (see Alarms & Commands), and platform AI is advisory-only — it reads, explains and recommends, but never issues control writes. Hard interlocks live in the IO modules and safety relays, below the API.

Public beta

The hosted service is in public beta. During the beta, free individual sandboxes and paid organisations are both arranged with our team: request access. The three credentials on this page — CIAM bearer, X-Api-Key, and site-PIN — are how API consumers authenticate; site-PIN applies on site servers only.

See also

• Authentication — how the server tells credentials apart, oid-based identity, and the conceptual model
• API keys — key classes, minting, rotation, expiry, and revocation
• Roles & membership — the owner / admin / member model
• API reference — the rendered OpenAPI for the endpoints the CLI and its client library call
• Public API surface — why the API is cell-direct and there is no separate gateway host