Skip to content

Identity

aidy has no user database. On every request it asks your host who the caller is, through the one catalog operation with role: identity.

"/api/me": {
"get": {
"x-aidy": { "name": "whoami", "role": "identity" }
}
}

The identity operation is a GET with no parameters and effect read. A catalog has exactly one. Like every role operation, it has no surfaces and is never offered to the model.

{
"subject": "u_123",
"tenant": "t_9",
"name": "Ada Lovelace",
"locale": "zh-CN",
"scopes": ["aidy:admin"]
}
Field Meaning
subject Required. The user’s stable id in your product.
tenant The organization, workspace or account the credential acts in, when your product has one.
name The user’s display name.
locale A BCP 47 language tag, such as en or zh-CN.
scopes aidy scopes. aidy:admin is the only one defined.

In Python, return the kit’s Identity model:

from aidy import Identity, op
@app.get("/api/me", openapi_extra=op("whoami", role="identity"))
async def whoami(request: Request) -> Identity:
user = current_user(request)
return Identity(subject=user.id, tenant=user.tenant_id, name=user.name, locale="zh-CN")
  1. A request reaches aidy with the user’s Authorization header, Cookie header, or both. Without either, aidy answers 401.
  2. aidy calls the identity operation with exactly those headers. This is an ordinary request: it carries no Aidy-Assertion.
  3. A 401 or 403 from your host becomes a 401 from aidy. Any other answer that is not a valid identity is an error.
  4. The identity is cached for 60 seconds per credential hash, so a burst of requests costs one identity call.

The credential itself is held in memory for the request or the run and never stored.

Sessions. A thread belongs to one (subject, tenant). The same user in two tenants has two separate histories, and nobody else can list, read, resume or delete them.

Calls. Every call aidy makes carries the assertion claims sub and ten, and your host checks them against the identity it resolves from the same credential (Delegation).

Settings and feedback. GET /aidy/v0/settings reads the current model chain; PUT and DELETE require the aidy:admin scope and answer 403 otherwise, and so does GET /aidy/v0/feedback, which lists the ratings on threads of the admin’s tenant. Settings hold the model chain only; knowledge is configured in code. The ModelSettings component of @aidy-dev/react is the admin form for it.

Per-user configuration. Runtime options that take a function receive the identity, for example instructions (which may also be async) and knowledge collections:

createAidy({
// ...
instructions: (identity) => `The user's tenant is ${identity.tenant}. Answer in ${identity.locale ?? 'en'}.`,
sources: [knowledge.source({ collections: (identity) => ['docs', `manuals/${identity.tenant}`] })],
});

aidy also fetches your OpenAPI document with the caller’s credential, so the catalog may differ between users. Hide an operation from users who may not call it, and the agent, MCP clients and the CLI will not offer it to them. Your API still authorizes every call either way.