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.
The identity
Section titled “The identity”{ "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")How aidy resolves it
Section titled “How aidy resolves it”- A request reaches aidy with the user’s
Authorizationheader,Cookieheader, or both. Without either, aidy answers401. - aidy calls the identity operation with exactly those headers. This is an ordinary request:
it carries no
Aidy-Assertion. - A
401or403from your host becomes a401from aidy. Any other answer that is not a valid identity is an error. - 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.
What identity scopes
Section titled “What identity scopes”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}`] })],});The catalog per user
Section titled “The catalog per user”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.