Skip to content
Tarn & Timber Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

Invited agents

Independent agent identities, owner consent and delegated browser sessions.

An invited agent has its own Auth0 identity in the agents database connection. The customer invites that identity, approves its permissions after fresh verification, and the recipient signs in independently and accepts the invitation. The shop stores consent in D1 and checks it on every delegated request. This is separate from a Poppy account grant and Account Token; granting one does not create the other.

Sign-in and delegation

  1. The owner prepares the invitation on /account/agents, approves the exact recipient and permissions, and sends it.
  2. The recipient authenticates through the confidential personal_agents client and the agents connection. The Auth0 proxy verifies its current email and connection before accepting consent.
  3. The Auth0 proxy uses the dedicated urn:poppy:invited-agent Custom Token Exchange profile. It binds the independent actor, approved owner and destination website client; it cannot use the Poppy API-token profile instead.
  4. Auth0 Session Delegation transfers the approved identity into the website. The storefront records the delegated session and verifies the returned actor claims. An ordinary human authentication response is refused.
  5. Calls for shared capabilities use web_agent_forwarder plus a signed invited-agent+jwt context. The API checks the live approval and retained delegation snapshot. The independent agent cannot become a customer or use human-only controls.

Required configuration

Setting or prerequisite Required value or action
Terraform switches enable_personal_agent_invitations, enable_session_delegation and enable_custom_token_exchange enabled
Login domain One verified HTTPS public login host for website_auth0_domain and proxy_auth0_issuer
Website entry website_initiate_login_uri = "https://<shop>/auth/initiate-login"; delegation uses HTTPS, non-localhost callbacks
Independent client callback https://<proxy-auth0-host>/personal-agents/callback
Platform registrations Owner-provisioned Auth0 Agent IDs in personal_agent_platform_ids; Terraform does not create these registrations
Proxy Auth0 configuration Merge personal_agent_proxy_auth0_config into the existing Auth0 proxy JSON as personalAgents
Independent client secret Bind sensitive output personal_agent_client_secret as AUTH0_PERSONAL_AGENT_CLIENT_SECRET
Claim namespace Keep PERSONAL_AGENT_CLAIM_NAMESPACE aligned with Terraform claim_namespace and the destination Action

Keep the canonical tenant domain for Management API and session-transfer identifiers. The public login domain is shared, but the independent client and connection keep agent credentials separate from customer credentials. Registered platform IDs describe the owner’s selected association; an email domain alone proves no vendor identity.

Deploy the invitation-aware account-verification Actions before exposing the UI: their purpose allowlists must accept invite-agent. The Auth0 proxy retains its existing signing, encryption, Management and service credentials, and needs read:users for recipient verification. The Action-only context secret remains separate from the shop service secret. The invitation email requires the storefront’s email binding and a configured sender.

The checkout’s docs/personal-agent-invitations-setup.md contains the full Auth0 proxy configuration, embedded-verification fallback and live acceptance procedure. infra/terraform/auth0/personal-agents.tf owns the client, connection, exchange profile and login Action.

Failure and revocation

Invitation delivery happens during the request. If sending fails, the owner can resend after the send claim expires; cron expires old invitations but does not deliver them. Recipient acceptance requires live consent and an unexpired invitation. Disconnecting the independent agent ends its shop authorization on the next use. Provider-session cleanup is separately retryable from the agents page; already-running remote work is not cancelled atomically.

See Poppy Sessions and grants for the other agent model and browser forwarding for request enforcement.

Was this page helpful?