Implement Session Delegation

​

Security model

• Both applications must be explicitly configured for this: the requesting application must be a confidential client able to create a Session Transfer Token, and the target application must explicitly opt in via allow_delegated_access — see Configure Session Delegation.
• The Session Transfer Token must be redeemed from the same IP address that was used to request it from the requesting application — see the IP-binding note under Redeem the Session Transfer Token below.
• The actor identity is recorded on the session (session.actor) and is available to your Actions and in tenant logs, using the same shape as the actor object passed to setActor().
• The session is ephemeral and short-lived — see Session behavior.
• No refresh tokens are issued, no MFA/consent/enrollment prompts are allowed, and existing active sessions block delegated access, all by design, to limit how far a delegated session can outlive or interact with a legitimate one.
• Delegated sessions generate dedicated tenant log event types, distinct from regular logins, so you can audit them separately.

​

Get a Session Transfer Token

curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type='urn:ietf:params:oauth:grant-type:token-exchange' \
  --data audience='urn:YOUR_AUTH0_TENANT_DOMAIN:session_transfer' \
  --data subject_token_type='{yourSubjectTokenType}' \
  --data subject_token='{signedJwtIdentifyingTheEndUser}' \
  --data actor_token_type='urn:ietf:params:oauth:token-type:id_token' \
  --data actor_token='{theAgentsAuth0IdToken}' \
  --data client_id='{yourClientId}' \
  --data client_secret='{yourClientSecret}'

{
  "access_token": "{sessionTransferToken}",
  "issued_token_type": "urn:auth0:params:oauth:token-type:session_transfer_token",
  "expires_in": 60
}

1. Detecting this is a session delegation request, by checking whether the requested audience ends in :session_transfer.
2. Authorizing the actor for the specific target user identified by subject_token, considering that this will create a session on behalf of that user — a more sensitive operation than granting scoped API access.
3. Calling setUserByConnection() with the connection the target application accepts. The Session Transfer Token is scoped to whichever single connection your Action selects. Read Target application reachability for the full detail on why this matters and how to select the right connection.
4. Calling setActor() to record the actor. This is required. Omitting it when requesting a Session Transfer Token returns a 400 error.

​

Redeem the Session Transfer Token

https://your-target-app.example.com/initiate-login?session_transfer_token={sessionTransferToken}

https://your-target-app.example.com/initiate-login?session_transfer_token={sessionTransferToken}&organization={orgId}

​

Handle the resulting tokens

{
  "sub": "auth0|end_user_id",
  "act": {
    "sub": "auth0|support_agent_id",
    "sub_profile": "human",
    "role": "support"
  }
}

const { act } = jwt.decode(id_token);
if (act) {
  // act.sub identifies the actor (the support agent); sub identifies the end user
  auditLog.record({ delegated: true, actorSub: act.sub });
}

​

Troubleshooting a failed redemption

1. Does your Action detect this is a session delegation request before applying its authorization policy? Check whether the requested audience ends in :session_transfer (event.resource_server.identifier) — an Action that doesn’t distinguish session delegation from plain API-access delegation may authorize or reject the wrong requests.
2. Is the subject user reachable through the connection your Action selected? The Session Transfer Token is scoped to whichever single connection your Action sets via setUserByConnection() — or the user’s primary connection, if using setUserById() instead. The target application can only redeem the token if that specific connection is enabled for it, not simply because the subject user also belongs to some other connection the target application allows.
3. Does the application calling Custom Token Exchange itself have access to that same connection? This is a setting on the calling (actor’s) application, separate from the target application, and easy to miss.
4. Does the target client have allow_delegated_access: true, and does session_transfer.allowed_authentication_methods include query? If allow_delegated_access isn’t set, Auth0 falls back to a normal login page instead of erroring. query is required since the token is passed as a query parameter, not a cookie. See Configure the target web application.
5. If passing an organization, is it included explicitly, and is the connection your Action selected linked to that organization? No interactive organization picker is allowed during a delegated session, so a missing or mismatched organization fails rather than prompting.
6. Does your initiate_login_uri route (or SDK helper) actually forward the session_transfer_token and organization query parameters through to /authorize? Some SDK login helpers don’t forward arbitrary query parameters by default — verify yours does.
7. Is there already an active Auth0 session for that browser and domain? Any existing session — the subject user’s own, or a previous delegated session for a different user — blocks a new delegated session. This is usually caused by the initiating and target applications sharing one Auth0 domain, and therefore one browser session cookie. Give the target application its own Custom Domain, distinct from the initiating application’s domain, so each gets a separate cookie. Without a Custom Domain, an alternative is to have the support agent copy the target application’s initiate_login_uri, with the token attached, into a separately-opened private/incognito browsing window. For the same reason, an agent must log out of a delegated session before a different one can be established for another user.
8. Was the token redeemed from a different IP than the one that requested it? Device binding rejects this — see the IP-binding note above.