Docs
Authentication

Authentication

Access tokens, browser sessions, capabilities, cross-origin rules and the responses to refused requests.

Every operation except the readiness probe is authenticated and authorized, and access is denied by default. The platform keeps no accounts, passwords or keys of its own: identity belongs to the host application and its identity provider, and the API verifies what they issue on every request.

Credentials

CallerCredentialCapabilities
A person in the browserThe host application's session cookie, from the API's own originread
A person in an appAn access token with praxis_principal_type set to userread
A service or an agentAn access token with praxis_principal_type set to serviceread or sync, one only

Send an access token as a bearer credential:

HTTP
GET /api/v1/intelligence/meta HTTP/1.1
Authorization: Bearer $PRAXIS_TOKEN

When an Authorization header is present, it alone is evaluated: a scheme other than Bearer, or an invalid token, is refused even if a valid session cookie is also sent.

Capabilities

CapabilityGrants
readEvery read model, plus the caller's own watchlist and alert read state
syncAsking the platform to pull its own source catalog, with POST /sync; the request carries no data

A service token carries exactly one capability in praxis_capability. Readers never synchronize, and the scheduler's service never reads. The OpenAPI document marks each operation's capability in x-praxis-access.

Access tokens

Access tokens are OAuth 2.0 access tokens in the JSON Web Token profile of RFC 9068, issued by the deployment's identity provider and verified against its JSON Web Key Set. A token is accepted only when all of these hold:

  • It is a signed JWT of at most 8,192 characters, with the typ header at+jwt, signed with RS256, PS256 or ES256 by a key of the issuer's key set.
  • iss and aud equal the deployment's configured issuer and audience.
  • It carries iss, aud, sub, iat and exp, and exp is at most 300 seconds after iat.
  • It is at most five minutes old, with five seconds of clock tolerance.
  • sub has 1 to 160 characters and no whitespace or control characters.
  • praxis_principal_type is user or service, and a service token carries praxis_capability.

Tokens live for minutes, not hours. Fetch a fresh token from your identity provider before it expires, rather than storing one.

In the hosted service, the credentials for your people, systems and agents are issued with your access. In a dedicated deployment, your own identity provider issues them. Request access to get either.

Browser clients

  • Same origin. A web application on the API's own origin can rely on the host's session cookie. Writes authenticated by the cookie, such as saving a watchlist, must carry the API's own Origin, which protects them from cross-site request forgery.
  • Other origins. A request with an Origin header must come from the API's own origin or from an origin the deployment approves; otherwise it is refused with 403 origin-not-allowed. Approved origins receive CORS headers without credentials, so web applications on another origin authenticate with bearer tokens.

Refused requests

StatusCodeWhen
401unauthorizedNo credentials, invalid credentials, or a cookie-authenticated write without the API's Origin
403forbiddenA verified caller without the operation's capability
403origin-not-allowedA browser origin that is neither the API's own nor approved

A 401 carries WWW-Authenticate: Bearer realm="praxis". Every refusal is a problem document, as Errors describes.

Personal state

The read capability includes the caller's own watchlist and alert read state, keyed to the verified identity, so they follow a person across devices. No request can read or change another caller's state. Published knowledge is read-only for every caller: no request can submit source data or change configuration. The full model is on the security page.