Poppy With Your Existing Login | Descope Documentation

When a personal agent asks to sign in to your site, your user has to prove which account the agent should act on. With External Authentication, that proof comes from the login page you already run.

Descope sends the user to your page, your backend tells Descope who signed in, and Descope continues to the consent screen and issues the agent's tokens.

This page is for companies whose customer login runs on another provider or on a system they built.

If Descope already runs your customer login, you have nothing to connect, so see Already on Descope. If your site has no accounts, see No login yet.

For the initial setup of the issuer and approval flow, see Agent Login.

The approval flow that Agent Login creates signs users in through Descope by default. That creates a second identity next to the account your user already has, and a user whose emails differ can end up with an agent connected to the wrong account.

External Authentication removes that second identity. Your user signs in on your own page, with your own password rules and MFA, and your backend names the account. Descope never sees the password.

The agent starts a device sign-in and shows your user a link and a code, or it sends your user to the sign-in page with the authorization code flow. Everything after that happens in the user's browser and on your backend.

Your user opens the link: The Descope approval flow reaches the External Authentication action and redirects the browser to your login URL with an external_auth_req_id query parameter.
Your user signs in on your page: Your login runs exactly as it does today. Keep the request ID through the login, for example in a hidden form field.
Your backend completes the request: After a successful login, your backend calls the complete external authentication endpoint with the request ID and the account's login ID.
Descope returns a redirect: The response carries a redirectUrl, and your backend sends the browser there.
Your user approves the agent: The flow continues to the consent screen. On approval, Descope issues the agent an access token and a refresh token.

Setting It Up

The setup has one Console change and one backend change. You need your Project ID and a Management Key for the backend call.

Open the approval flow

On the Agent Login page, open Log In & Consent Flow under Authentication.

Add the External Authentication action

Replace every authentication method in the flow with the External Authentication action. The flow then goes straight from it to the consent screen, as External Authentication describes. Leave the Update User Consent action in place after the screen.

Set the External Auth URL

Set External Auth URL to your login page, such as https://example.com/login. Descope appends external_auth_req_id to this URL.

Complete the request from your backend

After your user signs in, call the completion endpoint with the request ID. Then redirect the browser to the returned redirectUrl.

The completion call uses your Project ID and Management Key as a bearer credential. The loginId you send is the account the agent connects to, so send the identifier your system treats as the account, not one the user typed.

curl -X POST "https://api.descope.com/v1/mgmt/flow/externalauth/complete" \
  -H "Authorization: Bearer <Project ID>:<Management Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "externalAuthReqId": "<external_auth_req_id from the login URL>",
    "loginId": "customer@example.com",
    "emailVerified": true,
    "user": { "givenName": "Ada", "familyName": "Lovelace" }
  }'

The response contains redirectUrl. Redirect the browser there only when the value is an https URL.

The request ID works once, so a second call with the same ID fails. The External Authentication page lists every request field, including custom claims and tenants.

Keep the request ID through your login

A login page that redirects through other steps, such as MFA or a password reset, can drop the query parameter. Carry external_auth_req_id through every step, and validate its format before you use it. If the ID is lost, your user signs in but the agent's sign-in never completes.

Account Linking

The link between the agent and your account is the loginId your backend sends. Descope signs every later login with that ID into the same Descope user, so the ID has to belong to one account for good. An email works only if your system never moves an address to another account. Otherwise, send your own stable account ID.

The token's sub claim holds the Descope user ID, not your own account ID. To map it back, your backend can look up the user by login ID with load user and store the Descope user ID with your account. Northbound, the Descope sample store, sends the account's email as the login ID. It matches the token's email claim to a customer and reads the agent from the act.sub claim.

A user with two accounts at your company, such as a personal and a business account, gets a separate Session and refresh token for each. To keep their carts apart, your API can refuse a request whose access token names a different account than its Session used before. It returns the invalid_session error.

Accepting Agent Tokens on Your APIs

Your APIs trust tokens from your current provider, not from Descope. An agent's access token comes from Descope, so each API that agents call needs a way to accept it. The Poppy guides describe three ways, and you can mix them across your APIs.

Validate the Descope token directly: Your API or gateway checks the token with session validation or token introspection. It then maps the token to your account as Account Linking describes. Start here, because it needs no change to your current provider. Northbound works this way.
Validate at the edge and pass identity inward: A worker or gateway in front of your site validates the token and forwards the verified account, agent, and scopes to your origin in headers. Your origin then reads headers instead of tokens. The Poppy guides recommend this split for internal services, so a token never travels between your services.
Exchange for your current provider's token: Your backend exchanges the Descope token for a token from your current provider, and your APIs keep trusting only that provider. Your provider runs that exchange, so it has to support token exchange and trust Descope as an issuer.

Whichever you choose, check the scopes and the act claim on every request. Where your API keeps state across requests, such as a cart, it also verifies the Poppy-Session header before it uses the Session ID.

Your login proves who your user is. The consent screen then asks whether this agent can act for them, and with which scopes. Descope shows it after External Authentication returns, so your login page doesn't need to know anything about agents.

The default screen names the agent from its client metadata, such as "Claude", and the site it wants to access. It lists every scope the agent requested, with each scope's description, so write those descriptions in plain words.

The Poppy guides also recommend showing the following, which you can add 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 being connected: Your user sees which account they just signed in to.
How long access lasts: Your user knows when the agent needs to ask again.

Revocation From Your Side

Your system knows about events that Descope doesn't, such as a password reset or a suspected compromise. The Poppy guides recommend that you revoke a user's refresh tokens when either happens.

Your backend can revoke agentic identities through the Management API. A call with only userId revokes every agent acting for that user. The userId is the Descope user ID from the token's sub, not your own account ID. Your backend stores it when it links the account. The agent's Sessions then continue signed out, so it can still do anything that doesn't need the account.

You can also show your users their connected agents in your own account settings. List them with search agentic identities, and revoke one with its clientId and the same Descope user ID.

Every customer who approves an agent becomes a Descope user, with the login ID your backend sent. If you later move your customer login to Descope, those records carry over, and you no longer need External Authentication or a second token check on your APIs.

See Migrating to Descope for how to move users and sessions from your current provider.

Next Steps

These pages cover the rest of the setup:

Responsibilities: The Personal Agent Protocol overview shows what Descope runs and what stays with you.
MCP servers: Bring Your Own Auth uses the same External Authentication pattern on an MCP server.

Was this helpful?

On this page