Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.alterauth.com/llms.txt

Use this file to discover all available pages before exploring further.

Delegation is a user authorizing a specific agent to use one of the user’s grants. It exists because two security models conflict otherwise: the user owns the credential, but an AI agent needs to call the provider on the user’s behalf — and the agent should never see the credential itself. Without delegation, an agent that needed Stripe access on behalf of Alice would either (a) hold its own Stripe key (wrong principal, wrong audit trail) or (b) impersonate Alice somehow (no isolation between the agent’s actions and Alice’s). With delegation, Alice explicitly grants the named agent permission to use her Stripe connection. The credential stays in the vault, the agent stays scoped, and the audit row carries both identities.

​
How it’s created

Delegation is consented to at the same moment the user creates the grant. In a Connect session, the operator passes agent=<agent_id>; the consent screen shows the user the agent name; on Approve, Alter writes both the grant row and a delegation row binding that grant to that agent. A user can delegate a grant to many agents (each with its own delegation row), and an agent can receive delegations from many users (the agent ends up able to act on behalf of each).

​
How it’s used at runtime

The agent process calls agent.request() against the provider as usual. The backend:
  1. Resolves the calling agent from the API key signature.
  2. Looks up the delegations visible to that agent.
  3. Picks the grant matching the provider (and optionally the user, if the agent bridged a user_token).
  4. Injects the token from the user’s grant — never the agent’s own credentials, because the agent has none for this provider.
If the agent has delegations from multiple users on the same provider, the agent can disambiguate per-call via the user_token parameter (or by configuring user_token_getter at construction).

​
How it’s revoked

Three revocation surfaces, each removing a different layer:
  • User revokes the delegation (in the Wallet) — the agent loses access; the user’s underlying connection stays active.
  • User revokes the connection itself — both the connection and every delegation against it are torn down.
  • Operator revokes the delegation (app.revoke_delegation(grant_id, agent_id)) — the same effect as the user revoking the delegation, performed admin-side.
The agent’s first call after revocation raises NoDelegatedGrantError (or GrantRevokedError if the connection itself was revoked).

​
Delegation on managed secrets

The same model applies to managed secrets bound to a user. The user can consent to delegate a managed-secret grant to an agent via app.create_managed_secret_connect_session(), producing a delegation that lets the agent use the managed secret on the user’s behalf.

​
What’s next