Agent Login

Descope Envoy sets up an OAuth server for the AI agents that visit your customer-facing websites. In the Console sidebar and in these docs, Envoy appears as Agent Login. It follows the Personal Agent Protocol (Poppy), an open protocol that tells an agent where to authenticate and how to get approval from the person it works for.

Descope builds the sign-in and approval flow, turns on the project settings the protocol needs, and gives you a poppy.json file to publish on each site. One click sets all of it up, and you can change any piece afterward.

Use this guide if your users log in to your website or app and now send AI agents to act on their behalf. If you're protecting an MCP server instead, see MCP Servers.

Why Agents Need a Front Door

You built your login page for a person at a keyboard. An agent working for that person has no browser of its own and no password to type, so today it usually ends up in one of two places.

Either you block the agent with the rest of your bot traffic, and your user can't use the assistant they chose. Or it signs in as the user with their password or a copied session, and your backend sees an ordinary login. Once that happens, your system can't separate the user's actions from the agent's.

Agent Login offers a third option. The agent reads a single file at a known address on your domain, learns where to authenticate, and identifies itself by its own domain. Your user sees a screen that names the agent and what it wants to do for them, then approves or declines the request.

The agent then acts on behalf of your user instead of as your user. Your product sees two identities on every call: the user it already knows, and the agentic identity of the agent acting for them. You can scope that agent with policies, audit it, and cut it off without touching your user's account.

What Descope Sets Up for You

Set Up Agent Login configures four things in your project at once, so you don't assemble the protocol's requirements by hand.

• An approval flow: Descope builds the flow your users use to sign in and then approve or decline an agent, including the consent screen. It's a standard Descope flow, so you can edit the screens later or skip the consent screen entirely.
• Device Authentication: Agents show a link or a code, and the user approves on any device they already use. Descope turns on Device Authentication for the whole project, not only for this app.
• CIMD: Client ID Metadata Documents (CIMD) let an agent use its own HTTPS URL as its client ID, so an agent you have never met can still identify itself. Descope accepts only agents from the domains you approve.
• Published websites: Descope lists the domains you entered in protected_resources in your project's authorization server metadata, so an agent can confirm that the issuer answers for your site.

How an Agent Signs In

Nothing in this flow is specific to your site. The agent follows Poppy discovery and then standard OAuth, so any Poppy-capable agent gets through without instructions from you.

1. The agent finds your file: It requests https://yourdomain.com/.well-known/poppy.json and checks that organization.domain names the domain that served it.
2. The agent confirms the issuer answers for your site: It finds the issuer in your domain's protected resource metadata. Then it reads the issuer's OAuth metadata, which lists your domain in protected_resources. A copy of your file on someone else's domain doesn't match, and the agent stops.
3. The agent identifies itself: It presents its own metadata URL as its client ID through CIMD. Descope matches that URL against your approved agent domains and rejects anything else.
4. The agent starts a Session: The agent signs a Poppy-Session header on each request to your APIs. A request without an access token is signed out, so it covers anything that doesn't touch your user's account.
5. The agent asks your user to sign in: For device sign-in, Descope returns a link and a user code. The agent shows them to your user and polls for the result, as Device Authentication describes. An agent that can receive a browser redirect can use the authorization code flow instead, and both flows end at the same consent screen.
6. Your user decides: They open the link on any device and sign in with any method your product already supports. The consent screen names the agent and what it wants to do for them, and they approve or decline it there.
7. Descope issues the tokens: On approval, the agent gets an access token for the scopes your user granted. It also gets a refresh token, which gets new access tokens later without asking again. On a decline, the agent gets no tokens, and nothing changes in your user's account.

Where Agents Show Up Afterward

Every approval leaves a record you can return to. The first time a user approves an agent, Descope creates an agentic identity for that pairing. A second user approving the same agent gets a row of their own.

Each row carries the consent: the scopes your user granted, when they granted them, and when that consent expires. The row also has an Agent ID, which ties every token issuance, policy decision, and credential access in your audit log back to one agent working for one user.

The same page is where you end an agent's access. Revoking an identity invalidates the agent's refresh and access tokens, so its Poppy Sessions continue signed out until your user approves it again. Your user's own account and session continue untouched.

Setting Up Agent Login

You run the setup from the Agent Login page, under the Agentic Identity Hub section of the Descope Console. Before you enable Agent Login, that page already shows Your websites and Approved agents, in that order.

{
  "resource": "https://northbound.com",
  "authorization_servers": ["https://api.descope.com/v1/apps/P2g8xaiDl6AW80FoSXIQaS70FFkW"]
}

The poppy.json File

The file tells an agent that your site accepts agents and where to sign in. Descope generates one file per website and shows them under Client Settings, so you can copy the current version at any time.

{
  "protocol_version": "0.3",
  "organization": {
    "name": "Northbound",
    "domain": "northbound.com"
  },
  "auth": {
    "issuer": "https://api.descope.com/v1/apps/P2g8xaiDl6AW80FoSXIQaS70FFkW"
  },
  "web": {}
}

Descope generates only these fields. You can add the protocol's optional sections yourself before you publish, following the Personal Agent Protocol specification:

• auth.scopes and auth.scope_hints: Your scopes in plain words, and whether each one changes anything or touches personal data.
• apis: The APIs an agent can call, such as OpenAPI or MCP endpoints.
• agent: An agent of your own that a visiting agent can talk to.
• excluded_tasks and feedback: The tasks you don't offer to agents, and where an agent can report one it couldn't do.

Under the files, Manage clients opens Clients in the Agentic Identity Hub, where you manage your project's clients.

Changing the Setup Afterward

After setup, you manage everything from the same page. A Poppy compliant badge at the top confirms that your configuration still satisfies the protocol.

Authentication

The Authentication section shows whether Device Authentication is on and links to its settings. Log In & Consent Flow opens the flow Descope created, where you can change what your users see when they approve an agent.

The same flow also decides how your user signs in before approving, and you can change that sign-in to fit your product. Agent Login always runs this flow, even when your accounts live on another provider or on a login you built. In that case, the flow can use your login through federation or External Authentication, two of the Bring Your Own Auth options. Ways to Use Your Login compares them. If you'd rather have Descope handle sign-in, you can edit the flow to use a method such as OTP or any other method that Descope flows support.

The consent screen names the agent from its client metadata, such as "Claude". The screen also lists every scope the agent requested with the scope's description, so write those descriptions in plain words. The Poppy guides also recommend that the screen shows the following, and you can add each one by editing the flow's screen.

• The agent's domain: An agent chooses its own name, so the domain of its client_id is the part your user can trust.
• The account: Your user sees which account they just signed in to.
• How long access lasts: Your user knows when the agent has to ask again.

To skip the consent screen, enable Scopes auto approval on the flow's Update User Consent action. Descope still records the consent, so the approval still appears under the agent's identity.

Styling

The Styling section covers the logo, favicon, and colors on the page where your users approve an agent. Your other login pages keep their existing look. For the rest of your project's appearance, see Styles.

Your websites

Add or remove domains here. When you add a domain, publish its files there before agents can reach it.

Approved agents

The list controls which agents can connect to your users' accounts. Removing an agent stops new connections from it. To revoke access an agent already has, open Agentic Identity and revoke its identities.

Next Steps

Agent Login gets an agent through the door. What it can do once inside comes from the rest of the Hub:

• Policies: Policies control which scopes each agent can get.
• Resources: Resources define the APIs behind your site.
• Connected agents: The Agentic Identity page shows every agent acting for your users.

If your product also ships an MCP server, the same project covers it. See Use Cases for how external agents reach everything you build.