# 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.

*rungent between the surfaces people use and your product's API*

When a user approves "Stop server gpu-train-01?", rungent sends your API this request:

```http
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:

```json
"/api/me": { "get": { "x-rungent": { "name": "whoami", "role": "identity" } } }
```

```json
{ "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:

1. The signature verifies with a rungent public key pinned in your configuration, selected by
   `kid`. Never fetch keys from the request.
2. `aud` is your origin, `exp` has not passed (60 seconds of clock skew at most), and `jti` was
   not seen before.
3. `htm` and `bsh` match the request as received, and `htu` is your public origin followed by
   its path and query.
4. `sub` and `ten` equal the identity you resolved from the request's own credential.
5. `op` is the catalog operation that serves this method and path.
6. When that operation has `approval: always`, `apr` is present.

The helpers do it for you. In TypeScript, `verifyAssertion` runs checks 1 to 3 and `checkCall`
the rest; the [Quickstart](quickstart.md#verify-the-assertion) wraps them in a Hono middleware:

```ts
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](python.md#verify-the-assertion), which also covers
other languages. Three things are easy to get wrong:

- **The public URL.** `htu` names 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 `jti`s,
  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-Assertion` first; 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

```bash
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:

1. Generate a key with a new `kid`.
2. Add its public JWK to your API, next to the old one, and deploy.
3. Switch rungent's signing key to the new private key and deploy.
4. 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](http-api.md#host-assertions).

## Where to go next

[Forms and approvals](forms-and-approvals.md) shows where `apr` comes from and what the user
sees before it.
