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
| Caller | Credential | Capabilities |
|---|---|---|
| A person in the browser | The host application's session cookie, from the API's own origin | read |
| A person in an app | An access token with praxis_principal_type set to user | read |
| A service or an agent | An access token with praxis_principal_type set to service | read or sync, one only |
Send an access token as a bearer credential:
GET /api/v1/intelligence/meta HTTP/1.1
Authorization: Bearer $PRAXIS_TOKENWhen 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
| Capability | Grants |
|---|---|
read | Every read model, plus the caller's own watchlist and alert read state |
sync | Asking 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
typheaderat+jwt, signed with RS256, PS256 or ES256 by a key of the issuer's key set. issandaudequal the deployment's configured issuer and audience.- It carries
iss,aud,sub,iatandexp, andexpis at most 300 seconds afteriat. - It is at most five minutes old, with five seconds of clock tolerance.
subhas 1 to 160 characters and no whitespace or control characters.praxis_principal_typeisuserorservice, and a service token carriespraxis_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
Originheader must come from the API's own origin or from an origin the deployment approves; otherwise it is refused with403 origin-not-allowed. Approved origins receive CORS headers without credentials, so web applications on another origin authenticate with bearer tokens.
Refused requests
| Status | Code | When |
|---|---|---|
| 401 | unauthorized | No credentials, invalid credentials, or a cookie-authenticated write without the API's Origin |
| 403 | forbidden | A verified caller without the operation's capability |
| 403 | origin-not-allowed | A 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.