rungentConcepts
Acting as the user
rungent has no account in your product. It calls your API with the signed-in user's own credential and a short-lived signed assertion that names the operation; your API checks both and authorizes the call as it would a click in your UI.
When a user approves "Stop server gpu-train-01?", rungent sends your API this request:
POST /api/vms/vm-42/stop HTTP/1.1
Host: console.example.com
Authorization: Bearer <the user's own credential, as rungent received it>
Rungent-Assertion: eyJhbGciOiJFZERTQSIsImtpZCI6InJ1bmdlbnQtMjAyNi0xMSIsInR5cCI6InJ1bmdlbnQtY2FsbCtqd3QifQ…
Content-Type: application/json
{"forced":false}
Your API authenticates the credential as it always does, so the user's own permissions decide what the call may do. The assertion proves the rest: rungent sent this exact request, for this user, for this operation, after the user approved these arguments.
Who the user is#
rungent keeps no user database. It asks your API through the one catalog operation with
role: identity, a GET without parameters:
"/api/me": { "get": { "x-rungent": { "name": "whoami", "role": "identity" } } }
{ "subject": "u_123", "tenant": "t_9", "name": "Ada Lovelace", "locale": "zh-CN", "scopes": ["rungent:admin"] }
| Field | Meaning |
|---|---|
subject |
Required. The user's stable id in your product. |
tenant |
The organization or workspace the credential acts in, when your product has one. |
name |
The display name. |
locale |
A language tag such as en or zh-CN; the assistant answers in it unless the user writes in another. |
scopes |
rungent:admin lets the user change rungent's model settings and read feedback. |
rungent calls it with each request's credential, as an ordinary request without an assertion, and
remembers the answer for 60 seconds per credential. A 4xx from it makes rungent answer 401.
Conversations belong to one (subject, tenant): the same person in two tenants has two
histories, and nobody else can read them.
The user's credential#
rungent forwards the request's Authorization and Cookie headers exactly as it received them,
and no other header of the user's. In your web app that is the session the user already has,
because rungent is served on your own origin. MCP clients and the CLI send a bearer token your API
accepts.
rungent holds the credential in memory for the length of a run and never stores it. When it expires
mid-run, the call fails with credential_expired, and the user's next message brings a fresh one.
What the assertion binds#
Rungent-Assertion is a compact JWS signed with Ed25519 (alg: EdDSA, typ: rungent-call+jwt, and
the signing key's kid). Its claims tie it to one request:
| Claim | Meaning |
|---|---|
iss |
The rungent instance's URL |
aud |
Your origin, https://console.example.com |
sub, ten |
The user's subject and tenant |
op |
The catalog operation, stop_vm |
htm, htu |
The method, and your public origin followed by the path and query |
bsh |
base64url SHA-256 of the exact body bytes (the empty-body hash when there is none) |
apr |
The approval's id, when the user approved this call |
sid, rid, cid |
The conversation, run and tool call, for your audit log |
iat, exp |
Issued and expires, at most 60 seconds apart |
jti |
A unique id, so the assertion is used once |
A stolen assertion is worth very little: it names one method, one URL and one body, lives for a minute, and is accepted once.
Verify the assertion#
A request without Rungent-Assertion is an ordinary user request. With one, your API answers 401
with rungent_assertion_invalid unless all of these hold:
- The signature verifies with a rungent public key pinned in your configuration, selected by
kid. Never fetch keys from the request. audis your origin,exphas not passed (60 seconds of clock skew at most), andjtiwas not seen before.htmandbshmatch the request as received, andhtuis your public origin followed by its path and query.subandtenequal the identity you resolved from the request's own credential.opis the catalog operation that serves this method and path.- When that operation has
approval: always,apris present.
The helpers do it for you. In TypeScript, verifyAssertion runs checks 1 to 3 and checkCall
the rest; the Quickstart wraps them in a Hono middleware:
import { checkCall, importPublicKeys, verifyAssertion } from 'rungent/delegation';
const keys = await importPublicKeys([RUNGENT_PUBLIC_JWK]);
const claims = await verifyAssertion(assertion, {
keys,
audience: 'https://console.example.com',
request: { method: 'POST', url: 'https://console.example.com/api/vms/vm-42/stop', body: rawBody },
remember: (jti, until) => replays.add(jti, until), // false when it was seen before
});
checkCall(claims, { subject: user.id, tenant: user.tenantId, op: 'stop_vm', approval: 'always' });
In FastAPI, RungentHost is one middleware that matches the operation from your routes and runs all
six checks; see Python and other stacks, which also covers
other languages. Three things are easy to get wrong:
- The public URL.
htunames your public origin even when rungent reaches your API at an internal address. Behind a proxy that strips a path prefix, put the prefix back. - One replay cache. Every worker that serves your API must share the record of seen
jtis, or a replay may land on a worker that never saw it. - Stop at your edge. A gateway that forwards the request to other services removes
Rungent-Assertionfirst; the assertion is for the service that verified it.
Record actor = rungent, rid and apr in your audit log, so every change made through rungent
traces back to a run and an approval.
Keys and rotation#
npx rungent keys generate --kid rungent-2026-11 -o rungent-2026-11.private.jwk
It writes the private key, rungent's signing secret, to a new file only you can read, and prints the
public JWK for your API's configuration. rungent also serves the public key at
/.well-known/rungent-keys.json, for inspection. To rotate:
- Generate a key with a new
kid. - Add its public JWK to your API, next to the old one, and deploy.
- Switch rungent's signing key to the new private key and deploy.
- After two minutes (an assertion lives 60 seconds, plus 60 seconds of skew), remove the old public key from your API.
Calls from your API to rungent#
Two calls run the other way: completing a deferred task and a host job (one model completion
for your backend, such as a weekly report's summary). Your API signs each with an
Rungent-Host-Assertion: the same claims, signed with a key of yours that rungent pins in hostKeys,
with aud set to rungent's URL. See HTTP API.
Where to go next#
Forms and approvals shows where apr comes from and what the user
sees before it.
For agents: acting-as-the-user.mdEdit this page