Download all docs

Auth

Auth answers one question for every request: which circle is this call acting as, and may it run this operation? Authentication establishes the subject; authorization checks the capability. This page is the runtime’s reference entry to both; the concept that teaches the model is auth.

The circle is the subject

A request resolves to exactly one circle, and everything it touches — elements, the per-circle schema, the wallet — is scoped to that circle. There is one subject per request, never two. An agent that signs in is a circle exactly as a human is.

Two vehicles, one identity

The runtime accepts credentials by several vehicles, and they all resolve to the same internal auth context — the handler running your call cannot tell which carried it, and must not care:

  • triform_token cookie — the browser default, set on login.
  • Authorization: Bearer <jwt> — the programmatic default for CLI tools, agents, and backends.
  • trif_* API keys — minted bearer credentials, presented in the same slot.
  • ?auth=<jwt> query parameter — for WebSocket and screencast surfaces that cannot attach a header; short-lived only, since query strings leak into logs.

A crucial consequence: no write operation requires cookie auth over bearer. A call that “only works with cookies” is a client bug, not a server gate.

Three layers of authorization

  1. Per-operation auth level — declared in each element’s ops.yaml (none / read / write / admin, sometimes finer). The runtime reads it from generated code, so the requirement is uniform across HTTP, CLI, and agent tools. A call below the required level fails closed.
  2. api-token — the modifier that mints the credential you authenticate with (scoped, rotatable, revocable). It is the key, not the gate.
  3. auth-policy — the modifier that is the gate: attached to an element, it runs as middleware and returns 401 (no credential) or 403 (insufficient). Its cascade is restrictive — the stricter of parent and child wins.

So: the per-op level sets the baseline, api-token makes the key, auth-policy guards the door.

Related

  • Concept: auth — the full model (the teaching home)
  • Reference: /docs/api/authentication — headers, token pair, refresh flow
  • Pillar: Capabilities — the access-edge model behind authorization
  • Pillar: Runtime — where the auth check sits in the execution path
  • Element: api-token, auth-policy, oauth, rate-limit