Authentication¶

Consystence uses JWT-based authentication issued by the consystence-auth service. All API requests must include a valid access token.

OIDC discovery¶

The auth service publishes an OpenID Connect discovery document:

GET https://account.consystence.dev/.well-known/openid-configuration

Clients and site servers use this endpoint to discover token signing keys, supported flows, and endpoint URLs.

JWT claims¶

Access tokens include the following claims:

Claim	Type	Description
`sub`	string	Account ID (GUID)
`email`	string	Account email address
`org`	string	Current organisation ID (GUID)
`org_slug`	string	Current organisation slug
`org_role`	string	Role in the current organisation (`owner`, `admin`, `engineer`, `operator`, `viewer`)
`orgs`	string[]	All organisation IDs the account belongs to
`platform_admin`	boolean	`true` if the account is a platform administrator

Note

The org and org_role claims reflect the currently selected organisation. When a user switches orgs, a new token is issued.

Multi-org support¶

A single account can belong to multiple organisations. The platform handles this with an org context:

User logs in and receives a token scoped to their default organisation.
The UI presents an org switcher listing all memberships (from the orgs claim).
Switching orgs calls the token exchange endpoint to issue a new token scoped to the selected org.

Token lifecycle¶

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

{
  "email": "user@example.com",
  "password": "..."
}

Returns an access token and refresh token pair.

Token refresh¶

POST /auth/refresh
Content-Type: application/json

{
  "refresh_token": "..."
}

Returns a new access token. Refresh tokens are single-use — each refresh also returns a new refresh token.

Org switch¶

POST /auth/switch-org
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "org_id": "a3f1c9e0-7b2d-4e8a-b5f6-1d2e3f4a5b6c"
}

Returns a new access token scoped to the requested organisation.

Platform admin¶

Platform admin is a boolean claim (platform_admin: true) that grants unrestricted access to all organisations, sites, and processes. It is reserved for Consystence staff.

Warning

Platform admin status is determined solely by an approved @consystence.com email address. There is no manual flag or database column to set — the auth service derives it from the email domain at token issuance time.

Auth service endpoints¶

Endpoint	Method	Description
`/auth/register`	POST	Create a new account
`/auth/login`	POST	Authenticate and receive tokens
`/auth/refresh`	POST	Exchange a refresh token
`/auth/switch-org`	POST	Switch organisation context
`/auth/verify-email`	POST	Confirm email address
`/auth/verify-phone`	POST	Confirm phone number
`/auth/mfa/enable`	POST	Enable multi-factor authentication
`/auth/mfa/verify`	POST	Verify MFA code during login
`/auth/password/reset`	POST	Request a password reset
`/auth/password/change`	POST	Change password (authenticated)

Org resolution¶

When a request arrives at a site server, the organisation context is resolved through a cascade:

Subdomain — if the request is to bhp.consystence.cloud, the org is bhp.
JWT claim — the org claim in the access token.
Server state service — the site server's configured default organisation.

The first match wins. Subdomain resolution takes precedence so that bookmarked URLs always reach the correct org.