Skip to Content
These docs describe donkey-kit v0.2.1. Release notes
Identity

Live

Identity

By default the gateway sees your service, not the person the agent is acting for. That is fine until policy depends on who is asking. donkey.as_user() runs a block of agent code on behalf of a user:

from donkey_kit import Donkey async def answer(donkey: Donkey, access_token: str, question: str) -> None: openai = donkey.llm.client() async with donkey.as_user(token=access_token): # The gateway sees the user, not just the service. await openai.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": question}] )

Every governed model call in the block carries the user’s token, unchanged, so the gateway’s Trusted Agent Identity layer can apply per-user policy. The SDK runs no token exchange of its own: the gateway’s on-behalf-of policy trades the user token at your identity provider. So as_user() makes no Anypoint platform request and needs no connected-app credentials.

  • Scoped to the block. The user is bound to a context variable, like donkey.run(...). It reaches the asyncio tasks the block starts and never leaks into a concurrent task that entered no block. A nested block restores the outer user when it exits. Sync code uses a plain with (below).
  • Forwarded as is. The SDK doesn’t read the token’s claims or expiry. An expired token comes back from the gateway as a typed error.
  • Model calls and MCP tools. The user token goes on requests to the LLM proxy, and on the MCP tool sets you bind inside the block. Calls to the Anypoint platform keep the service’s own credentials, and a request to any other origin never carries it.
  • Never to an untrusted project URL. You pass the token in code, so it follows the same rule as any credential that doesn’t come from the project config files. If llm_proxy_url comes from the working directory’s .donkey-kit.toml or .donkey-kit.local.toml, as_user() raises a ConfigError unless DONKEY_TRUST_PROJECT_CONFIG is set. A discovered MCP tool set does the same check for base_url, the source of its server URLs. To fix it, set the URL in the environment or set the opt-in. See Which credentials a URL receives.

In sync code

as_user() is a plain context manager too, for a Flask or Django handler, the sync client, or LangGraph’s invoke():

from donkey_kit import Donkey def answer(donkey: Donkey, access_token: str, question: str) -> None: openai = donkey.llm.client(sync=True) with donkey.as_user(token=access_token): openai.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": question}] )

It binds the same context variable as async with, so the two nest and restore each other. Each thread of a threaded server starts with no user bound, so one request’s user never reaches another request’s thread.

The sync client runs in the default client-id auth mode only. In the jwt and bearer modes a blocking call raises a ConfigError, so use async with there.

Configuring the header

The token rides as Authorization: Bearer <token>, the header the gateway’s JWT Validation and on-behalf-of policies read. You can override it:

Env varDonkeyConfig fieldDefaultMeaning
DONKEY_USER_TOKEN_HEADERuser_token_headerAuthorizationThe request header the user token rides in. Authorization carries it as Bearer <token>; any other header carries the raw token.

as_user() forwards the token you pass, unchanged. JWT Validation accepts it only if its audience names the gateway API (for an MCP tool set, the MCP instance). A user’s login token usually names your app instead: exchange it at your identity provider for one issued to the gateway’s audience before you pass it in. Pass an access token, not an OIDC ID token: an ID token is issued to your app, not to the gateway.

In the jwt and bearer auth modes the data-plane token already rides in Authorization, so as_user() raises a ConfigError until you set user_token_header to the header your gateway reads the user token from.

The problem this solves

An HR bot must not answer a manager’s salary question about a different manager’s report.

That decision belongs to the gateway — it is the component that holds the identity policy, the org-chart relationships, and the audit obligation. DDK’s job is to get the user’s token onto the request correctly so the gateway can make the call it is already able to make.

Where the boundary sits

DDK does not implement authorisation logic. Trusted Agent Identity is a MuleSoft gateway feature. DDK forwards the user token and places the header — nothing more. “Check the user’s role in the SDK” is client-side enforcement, and it is on the will-not-build list: code in your process can be bypassed by code in your process.

No silent fallback: a deliberate hard failure

The failure mode to design against is a lost user token that lets the call quietly proceed under the service identity. Per-user policy would stop applying while everything still appears to work.

So inside as_user() a model call carries the user’s token or it is not sent. A missing user token is a deliberate hard failure: it raises AuthError, with a .remediation, before any request leaves the process.

What went wrongWhen it raisesThe error names
No token: empty, blank or Nonedonkey.as_user(...) itselfthe missing token
An approved tool resumed with another user’s tokenwhen the tool would runthe approval and the tool
A native approval resumed without retained requester statewhen the tool would runthe approval and the tool; request a fresh approval
A per-tool MCP binding called under a different user from the one it was bound forwhen the tool would be calledthe tool and its server

The same rule holds across an approval. A tool that waits for a human runs as the user who asked for it, with their token and attribution, wherever it is resumed. Resuming it inside as_user() under a different token raises AuthError instead of running it as someone else. Native approvals also fail closed when requester state is lost after a restart, another process or eviction; binding the resumer with as_user() cannot recover that evidence. See Who a resumed call runs as.

MCP tools follow it too. A binding sends the identity it was bound with, so bind inside the block that runs the agent. A per-tool binding (LangGraph, LlamaIndex, the Anthropic SDK) called under a different user raises AuthError instead of sending the call as someone else. “A different user” means another token, a user’s binding called outside any block, or a service binding called inside one.

Whole-server MCP bindings are not checked. ADK, Strands, the OpenAI Agents SDK, Agent Framework and CrewAI make their own MCP calls, out of the SDK’s sight. An agent built with one at startup and run inside as_user() sends its model calls as the user and its tool calls as your service. Bind those inside the as_user() block that uses them. See Acting for a user.

The errors and the SDK’s logs never contain the token itself. There is no setting that enables a fallback to the service identity, and none will be added: a block that can’t run as the user doesn’t run.

The receiving transport checks its own configuration before every user-token send, even if another Donkey created the as_user() scope. On a reused HTTP request, the SDK restores or removes its previous user-header write before applying the current scope; a token from a finished scope is not retained.

Adapters that only take connection_kwargs() and don’t route through the shared transport never see the block, so their calls are not made as the user.

Last updated on