---
title: Invited agents
description: Independent agent identities, owner consent and delegated browser sessions.
sidebar:
  order: 7
---

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](/poppy) for the other agent model and
[browser forwarding](/architecture/request-flows/poppy-agents#web-agent-forwarder) for request enforcement.