The Trust Boundary

For integrators — anyone writing code that calls the Temper API, whether a service, a
script, or an agent runtime. Also relevant to operators, who configure the boundary their
deployment enforces.

If you are an individual user authenticating through the CLI, the short version is: install
the binary, run temper init, run temper auth login, then temper auth request-access and
wait for an admin to approve. This page is about what the server enforces, not how to run a
login command.

What the boundary is

Every call to Temper — HTTP or MCP — crosses the same two-gate boundary, enforced in one place
(the auth seam) and projected onto two surfaces (the HTTP API and the MCP server). A call that
fails either gate is refused before any data is touched.

The two gates, stated as outcomes (not levels):

Authentication (401 on failure). The caller presents a Bearer JWT. The server validates
its signature against exactly one issuer's keys, checks its audience, checks its expiry, and
resolves it to a profile. If any of these fail, the response is 401 UNAUTHORIZED. The
caller fixes the token and retries.

System access (403 on failure). The authenticated profile must have approved standing
on this instance. A brand-new signup is born denied; request-access moves it to
requested; only an admin can move it to approved. If the profile is not approved, the
response is 403 SYSTEM_ACCESS_REQUIRED with a payload explaining why. There is no path from
signup to a successful data call that does not pass through an admin.

Registration is not admission, and nothing fails in between. A machine can register, mint a
token, pass authentication, and be refused only at the system-access gate — on every data call.
Nothing warns earlier. This is the single most valuable thing to know about the boundary if you
are automating against it.

The API base URL

The API base is <origin>/api — the origin plus an /api prefix the client prepends per
request. For the hosted instance that is https://temperkb.io/api. Verify it live:

GET https://temperkb.io/api/health → 200 (unauthenticated)

The published API reference — every endpoint, every schema, rendered from the router's
OpenAPI spec — is at docs.temperkb.io. Link the site root, not
a deep page; per-endpoint pages have import-generated ids that may not survive a re-import.

How a caller obtains the audience

The audience is the string the JWT must carry for the server to accept it. Do not guess it;
discover it — and discover it from the door that matches the surface you are calling.

HTTP callers (CLI, machine clients, SDK users):

GET <origin>/.well-known/oauth-authorization-server

The response includes a resource field carrying exactly the audience the HTTP surface
validates. For the hosted instance:

{ "issuer": "https://temperkb.io/",
  "resource": "https://temperkb.io/api" }

On a self-hosted SAML instance (Temper AS), the response has no resource field. That
authorization server serves a fixed set of resources — the instance's API audience and, when the
operator configured one, its MCP resource — and a caller may name one of them with the RFC 8707
resource parameter (or Auth0's audience spelling) at /oauth/authorize. A requested resource
outside that set is refused; a request that names none gets the API audience. HTTP callers can
simply omit it.

MCP clients read the RFC 9728 protected-resource metadata instead:

GET <origin>/.well-known/oauth-protected-resource

Its resource is the MCP surface's own audience — MCP_AUDIENCE when the operator set it
(conventionally the MCP server URL itself, which is what lets conformant MCP clients pass their
resource-matches-the-server-URL-or-origin check), AUTH_AUDIENCE otherwise. A conformant MCP
client requests that resource, and the token it receives names it.

Each discovery door answers for its surface; both doors accept the same tokens. The HTTP
and MCP doors accept the same instance audience set. When MCP_AUDIENCE differs from
AUTH_AUDIENCE, a token naming either resource authenticates at either door. This is
deliberate: the MCP service relays the caller through the API, and the two transports are one
authorization domain. The audience split satisfies resource discovery and token targeting; it
is not a least-privilege boundary between the transports. A token naming any other audience is
refused at both.

Who signs what in Temper-AS mode

On a SAML instance two different signatures are in play, and they are not interchangeable:

The external SAML identity provider authenticates the user and signs the SAML
assertion it posts back to Temper. Temper's authorization server verifies that signature
against the IdP certificate the operator configured.

Temper's authorization server signs the OAuth access token (EdDSA). That token is the
only thing either door ever sees, and it is verified against the authorization server's own
published keys — the instance's one issuer.

So the issuer a caller's token names is always the Temper instance, never the SAML IdP. The
resource the flow requested is carried through the authorization code and every refresh of
the session, so a refreshed token keeps the audience its login was granted.

The error contract

Every error response carries {"error":{"code":"…","message":"…","details"?:…}}. The code
is a stable string; details rides only SYSTEM_ACCESS_REQUIRED and PLAN_REFUSED.

status	code	means	caller does	retry
401	`UNAUTHORIZED`	missing or malformed Bearer	fix the header	no
401	`UNAUTHORIZED`	invalid or expired token — signature, issuer, audience, expiry	refresh; re-check audience against discovery	once
401	`UNAUTHORIZED`	auth service unavailable (JWKS fetch)	back off	yes
401	`UNAUTHORIZED`	account deactivated	stop; contact operator	no
401	`UNAUTHORIZED`	machine client not registered — message names the exact provision command	hand the `client_id` to an operator	no
403	`SYSTEM_ACCESS_REQUIRED`	authentic, no approved standing; `details.refusal.kind` says which	human: `request-access`. machine: an admin must approve	no
403	`FORBIDDEN`	refused, deliberately message-less (no capability disclosure)	obtain the grant out of band	no
403	`FORBIDDEN_DETAIL`	refused, message names the capability	obtain it	no
404	`NOT_FOUND`	absent or masked (a probe is not an existence oracle)	infer nothing either way	no
400	`PRECONDITION_NOT_HONOURED`	a write carried `If-Match`, `If-None-Match` or `If-Unmodified-Since` on a route that does not evaluate it; nothing was applied. Answered only to a caller the route already admits: an unauthenticated or refused caller gets the answer it gets without the header	resend without the header to write unconditionally	no
400	`PLAN_REFUSED`	composition invalid; `details.refusals[]` lists every reason	repair all in one round trip	no
400, 413, 415, 422	`UNREADABLE_PLAN`	the body is not a readable composition (malformed JSON, wrong content type, over the door's limit, a wrong type); no `details`, and the message repeats at most 1024 bytes of what failed	fix the body; there is no plan to refuse yet	no
409	`INGEST_ENDED`	append or finalize on an ingest that has ended (`cancelled` or `abandoned`); not resumable	start a new upload	no
422	`CONTENT_INTEGRITY`	stored bytes fail the hash; not resumable	re-upload from scratch	no
500	`INTERNAL_ERROR`	server fault	back off	yes

MCP renders these as JSON-RPC errors with prose — no status, no code, no details: a
caller fault the agent can repair (a refused or unreadable plan, a refused search) as -32602,
the terminal auth refusals as -32600, everything else as -32603. An integrator writing a service targets HTTP; MCP is an agent-runtime target.

The machine-principal sharp edge

A machine cannot use the remedy its own 403 advertises. The SYSTEM_ACCESS_REQUIRED
payload includes a cli_command (temper auth request-access), but machines can never
request access — the state transition that moves a profile from denied to requested is
human-only. The only remedy is an admin running temper admin access approve <profile_id>, and
the payload does not name it. State this in any automation you write, because nothing in
the product will.

And it is invisible until it fails: a registered-but-unapproved machine mints a token (200),
passes JWT validation, passes the registration gate, passes authentication — and is refused
only at the system-access gate, on every data call. Nothing warns earlier.

Machine principals and headless sessions

A machine principal is not a user with a long-lived token; it is its own kind of principal,
registered ahead of time. The authentication path is the same Bearer JWT, minted by the same
issuer, validated by the same two gates. What differs is how the token is obtained — a
machine credential exchange, not a browser login.

A headless CLI session (a cloud agent, a CI pipeline) can authenticate without browser OAuth
by setting environment variables:

Variable	Purpose	Required?
`TEMPER_TOKEN`	JWT access token for the API	Yes
`TEMPER_API_URL`	API base URL (e.g. `https://temperkb.io/api`)	Yes — without it the client has no endpoint and fails at send time
`TEMPER_PROVIDER`	Auth provider name that issued the token	No — defaults to `auth0`
`TEMPER_DEVICE_ID`	Stable device id for this session	No — a fresh UUIDv7 is generated if unset

Some hosts keep the credential out of the session entirely: an egress proxy attaches it to
requests bound for the API host, so no token is ever in the environment. For those, set
TEMPER_AUTH=ambient instead of TEMPER_TOKEN. The CLI then sends requests without an
Authorization header for the proxy to add, never reads or writes auth.json, and learns who
it is from GET /api/profile.
The validation is unchanged: whatever the proxy attaches passes the same two gates. Setting
both TEMPER_AUTH=ambient and TEMPER_TOKEN is refused as a configuration error, and so is
any other TEMPER_AUTH value.

Such a session needs no temper init either. Set TEMPER_VAULT to a directory for the local
projection, and commands that resolve a vault read the absent ~/.config/temper/config.toml as
defaults. Without a named vault, the config file is still required.

A human-driven agent (Claude Code, an IDE plugin) authenticates as the human: the human
runs temper auth login, the CLI caches the token, and the agent inherits it by driving the
CLI. There is no separate "agent identity" — the agent is the human, through the CLI.

MCP is a second surface, not a second API

The MCP server runs on a different base path (/mcp, no /api prefix) with a JSON-RPC
transport, but the authentication is identical — same issuer, the same accepted audience set
(the API audience and, when configured, the MCP surface's own MCP_AUDIENCE), same two
gates. The difference is transport and tool surface (40 registered MCP tools against 105 REST
paths — the REST count from the router's generated openapi.json, the tool count from the
MCP server's registered tool list). An integrator writing a service targets HTTP; MCP is an
agent-runtime target. The SDKs are generated from the OpenAPI spec, i.e. HTTP-only.

The Trust Boundary

What the boundary is#

The API base URL#

How a caller obtains the audience#

Who signs what in Temper-AS mode#

The error contract#

The machine-principal sharp edge#

Machine principals and headless sessions#

MCP is a second surface, not a second API#

Further reading#