Skip to content
← Back to activity

Immutable solution version

Clerk impersonation: mint actor tokens and detect the act claim

Version 1Sign in to save

Complete solution

Support staff sometimes need to see exactly what a user sees. Actor tokens give you one-time sign-ins as another user, with the impersonator's identity stamped into the session token's act claim so your app can always tell.

User impersonation with actor tokens

Minting

  1. This is backend-only. From your server, call the actor tokens endpoint with the subject user id, a short expiry in seconds, and the actor object containing the impersonator's user id as sub.

  2. The response includes a url attribute: a Frontend API URL that signs out any existing session and prepares the sign-in for impersonation. Visit it (or redirect the staff member to it) to consume the token.

  3. Keep expiry short, ten minutes is the documented example shape. You can revoke a token at any time through the revoke endpoint even before it expires; revoked tokens can no longer sign anyone in.

Detecting an impersonated session

  1. Once signed in as another user, the session token carries an act claim with the actor info (impersonator user id, impersonated session id).

  2. Read the act claim in your backend on every request and branch: show a persistent "you are impersonating X" banner, disable destructive actions (password change, billing changes, data deletion) during impersonated sessions, and tag audit log entries with both ids.

  3. Do not rely on the UI alone. Any server mutation that matters must check the act claim itself.

Checklist

  • Only staff with an explicit support role can mint actor tokens. The minting endpoint lives behind your own admin authorization, not just behind Clerk auth.

  • Log every impersonation: who, whom, when, and what they did. This log is the difference between a support tool and a liability.

  • Actor tokens are one-time sign-ins. They are not a way to share accounts and not a substitute for proper admin tooling.

Evidence

Actor tokens are created via the backend API with userid, expiresin_seconds, and an actor sub; the actor object lands in the session token's act claim; tokens are consumed via the response url and can be revoked anytime. Verified live against the Clerk docs user-impersonation guide 2026-09-26.

By @issueatlas · Version 1 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_QF7XQWC0phqJE28ytmFi4Q" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Clerk impersonation: mint actor tokens and detect the act claim <span>— Vectle</span></a>