Delegation
aidy never holds a privilege of its own. Every call it makes to your API acts as the user who asked, and your API authorizes it exactly as it authorizes your UI.
Two headers
Section titled “Two headers”POST /api/vm/vm-42/stop HTTP/1.1Host: console.example.comAuthorization: Bearer <the user's own credential, as aidy received it>Aidy-Assertion: <compact JWS>Content-Type: application/json
{"forced":false}Authorization(andCookie, when the user signed in with one) is the user’s credential, passed through unchanged. Your API authenticates it as usual.Aidy-Assertionproves that this exact request came from aidy, for this user, inside a particular run, and, for operations that need approval, after the user approved these exact arguments.
A request without Aidy-Assertion is an ordinary user request. aidy’s own fetches of your
OpenAPI document and identity operation are ordinary requests too.
The assertion
Section titled “The assertion”The assertion is a compact JWS signed with EdDSA (Ed25519). Its protected header is:
{ "alg": "EdDSA", "kid": "aidy-2026-11", "typ": "aidy-call+jwt" }Its claims:
| Claim | Meaning |
|---|---|
iss |
The aidy instance URL. |
aud |
Your host origin, https://console.example.com. |
sub |
The subject of the user’s identity. |
ten |
The user’s tenant, when there is one. |
sid, rid, cid |
Session, run and tool-call ids, for audit. Over MCP, cid is the MCP request id. |
op |
The catalog operation name, stop_vm. |
htm |
The HTTP method. |
htu |
The host’s public origin followed by the request path and query string. |
bsh |
base64url SHA-256 of the exact request body bytes; the empty-body hash when there is none. |
apr |
The approval id, present when the user approved this call. |
iat, exp |
Issued at and expiry, in seconds. exp - iat is at most 60. |
jti |
A unique id, for replay protection. |
Host verification
Section titled “Host verification”With an assertion present, your host must answer 401 with aidy_assertion_invalid unless all
of these hold:
- The signature verifies with a pinned aidy public key, selected by
kid. Keys come from your configuration, never from the request. audis your origin,exphas not passed (at most 60 seconds of clock skew), andjtiwas not seen before itsexp.htm,htuandbshmatch the request as received.subandtenequal the identity your host resolved fromAuthorization.opis the catalog operation that serves this method and path.- When
ophasapproval: always,apris present.
Each host kit implements these checks in one call:
| Host | Kit |
|---|---|
| Python (FastAPI) | aidy.fastapi.AidyHost middleware, or verify_assertion and check_call |
| TypeScript | verifyAssertion and checkCall from @aidy-dev/spec/delegation |
| Go | Verified in-tree against the shared vectors in conformance/delegation/vectors.json |
from aidy import check_call, verify_assertion
claims = verify_assertion( token, keys=keys, audience="https://console.example.com", method="POST", url=full_url_as_sent, body=raw_body, remember=lambda jti, until: cache.add(jti, until), # False when seen before)check_call(claims, subject=user.id, tenant=user.tenant_id, op="stop_vm", approval="always")Record actor = aidy, rid and apr in your audit log, so every agent action traces back to a
run and an approval.
Approval binding
Section titled “Approval binding”When a call needs approval, aidy freezes the validated arguments, computes
argsHash = base64url(SHA-256(JCS(arguments))) with JCS from RFC 8785, and persists the
approval with that hash. On resume, aidy executes only the frozen arguments, and only if the
stored hash still matches. Each approval executes at most once, even when two workers race. The
assertion of that call carries the approval id as apr. See
Approvals.
Credential lifetime
Section titled “Credential lifetime”aidy keeps the user’s credential in memory for the duration of a run and never persists it.
When the credential expires mid-run, the call fails with credential_expired, and the run
pauses until the user’s next request supplies a fresh one. Deferred tasks are completed by the
host and need no user credential.
aidy keys generate --kid aidy-2026-11 -o aidy-2026-11.private.jwkaidy keys generate writes an Ed25519 key pair. The private JWK is aidy’s signing key, a
configuration secret written to a new 0600 file and never printed. The public JWK is printed
for your host’s configuration:
{ "kty": "OKP", "crv": "Ed25519", "x": "…", "kid": "aidy-2026-11" }aidy also serves its public keys at /.well-known/aidy-keys.json, for inspection. Hosts pin
keys in configuration and do not fetch them at verification time. Both JWKs are portable,
{kty, crv, x, kid} and {kty, crv, x, d, kid} without alg, key_ops or ext, so Node,
Bun, Deno and workerd import them alike. Load the private key in code with importSigningKey
from @aidy-dev/spec/delegation, which also accepts a Node-exported JWK with alg.
Rotation. Generate a key with a new kid, publish its public key to every host first, then
switch aidy’s signing key. Remove the old public key from hosts once no assertion signed with it
can still be accepted: assertions live at most 60 seconds, plus 60 seconds of skew.
The host’s own assertion
Section titled “The host’s own assertion”Two calls run the other way, from your host to aidy: completing a deferred task
(POST /aidy/v0/tasks/{taskId}) and a host job (POST /aidy/v0/generate).
Your host signs each with an Aidy-Host-Assertion: an EdDSA JWS from a host key pinned in
aidy’s hostKeys (AIDY_HOST_KEYS for aidy-server), over the same claims:
audis aidy’s URL,issyour host’s;htuis the origin of aidy’s public URL followed by the path and query you post to, even when a proxy forwards the request to an internal address, so it works behind a proxy;bshhashes the exact body;exp - iatis at most 60 seconds; eachjtiis accepted once;opis the deferred operation, orgenerate;sub(andten) say whom the call is for.
A failed check is 401 aidy_assertion_invalid. See the
HTTP API.
Host jobs
Section titled “Host jobs”A host job is one model completion your backend asks for outside a conversation: a scheduled
report’s summary, a title for an imported item. POST /aidy/v0/generate runs it over the same
model chain as runs, with no tools and no thread.
import { importSigningKey, sha256, signAssertion } from '@aidy-dev/spec/delegation';
const key = await importSigningKey(JSON.parse(process.env.HOST_PRIVATE_JWK!)); // its public half is in aidy's hostKeysconst url = 'https://console.example.com/aidy/v0/generate'; // aidy's public URLconst body = JSON.stringify({ instructions: "Write the weekly report's summary.", input: 'Closed: 14 items. Opened: 9. Slowest: I-1647 (6 days).', schema: { type: 'object', properties: { headline: { type: 'string' } }, required: ['headline'] },});const now = Math.floor(Date.now() / 1000);const assertion = await signAssertion( { iss: 'https://console.example.com', aud: 'https://console.example.com', sub: 'u_1', // whom the job is for sid: 'weekly-report', rid: 'weekly-report-2026-47', cid: 'weekly-report-2026-47', op: 'generate', htm: 'POST', htu: url, bsh: await sha256(body), iat: now, exp: now + 60, jti: crypto.randomUUID(), }, key,);const response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Aidy-Host-Assertion': assertion }, body,});const { object } = await response.json(); // { headline: "…" }- The body is
{instructions?, input, schema?, maxOutputTokens?};inputis required. - Without
schemathe answer is{text}. With it, the model is asked for JSON (with the provider’s JSON mode, where it has one) and the answer is{object}, valid against the schema. An invalid answer is sent back to the same endpoint once, with what is wrong; a second one is422 invalid_output. maxOutputTokensof the request wins over the endpoint’s. The job is bounded by the run timeout (504 timeout), and503 model_unavailablemeans no endpoint could answer.
The Python kit has no signing helper. A Python host signs the same claims with any Ed25519 JWS
library, or with cryptography (a dependency of the kit) directly:
import base64, hashlib, json, time, uuidfrom cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
def b64url(data: bytes) -> str: return base64.urlsafe_b64encode(data).rstrip(b"=").decode()
def host_assertion(key: Ed25519PrivateKey, kid: str, url: str, body: bytes, sub: str) -> str: now = int(time.time()) header = {"alg": "EdDSA", "kid": kid, "typ": "aidy-call+jwt"} claims = { "iss": "https://console.example.com", "aud": "https://console.example.com", "sub": sub, "sid": "job", "rid": "job", "cid": "job", "op": "generate", "htm": "POST", "htu": url, "bsh": b64url(hashlib.sha256(body).digest()), "iat": now, "exp": now + 60, "jti": str(uuid.uuid4()), } signing_input = f"{b64url(json.dumps(header).encode())}.{b64url(json.dumps(claims).encode())}" return f"{signing_input}.{b64url(key.sign(signing_input.encode()))}"