Skip to content

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.

POST /api/vm/vm-42/stop HTTP/1.1
Host: console.example.com
Authorization: Bearer <the user's own credential, as aidy received it>
Aidy-Assertion: <compact JWS>
Content-Type: application/json
{"forced":false}
  • Authorization (and Cookie, when the user signed in with one) is the user’s credential, passed through unchanged. Your API authenticates it as usual.
  • Aidy-Assertion proves 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 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.

With an assertion present, your host must answer 401 with aidy_assertion_invalid unless all of these hold:

  1. The signature verifies with a pinned aidy public key, selected by kid. Keys come from your configuration, never from the request.
  2. aud is your origin, exp has not passed (at most 60 seconds of clock skew), and jti was not seen before its exp.
  3. htm, htu and bsh match the request as received.
  4. sub and ten equal the identity your host resolved from Authorization.
  5. op is the catalog operation that serves this method and path.
  6. When op has approval: always, apr is 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.

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.

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.

Terminal window
aidy keys generate --kid aidy-2026-11 -o aidy-2026-11.private.jwk

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

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:

  • aud is aidy’s URL, iss your host’s;
  • htu is 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;
  • bsh hashes the exact body; exp - iat is at most 60 seconds; each jti is accepted once;
  • op is the deferred operation, or generate; sub (and ten) say whom the call is for.

A failed check is 401 aidy_assertion_invalid. See the HTTP API.

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 hostKeys
const url = 'https://console.example.com/aidy/v0/generate'; // aidy's public URL
const 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?}; input is required.
  • Without schema the 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 is 422 invalid_output.
  • maxOutputTokens of the request wins over the endpoint’s. The job is bounded by the run timeout (504 timeout), and 503 model_unavailable means 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, uuid
from 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()))}"