Sign in
platform

Exchange For Impersonation Token

Exchange the caller's own SPA access token for a short-lived impersonation token.

The FGA gate lives on the router include (see :mod:app.authorization.matrix): this POST requires editor on the dock impersonation module instance, so impersonation is delegable per persona rather than tied to blanket app-dock ownership. Two refusals layer on top:

  • 401 No token to exchange — only end users can drive this flow, so service-account principals are rejected outright. The SPA token is reused as the subject_token for RFC 8693, so an impersonating session cannot itself act as the subject of another exchange (the dock identity layer rejects act on a token that already has act set).
post/api/platform/impersonation/exchange

Request body

targetUserIdstring nullable

Auth0 user_id of the user to impersonate. Preferred over targetEmail because it disambiguates the same-email-across-connections case. Always available from the Users page row.

targetEmailstring nullable

Email of the user to impersonate. Used when targetUserId is not provided; the dock backend resolves it via GET /users-by-email and refuses with 409 if the email matches multiple Auth0 users.

targetNamestring nullable

Optional display name passed through for the SPA banner.

mode'full' | 'readonly'

full permits writes; readonly blocks every non-safe HTTP method server-side.

Response

Successful Response

accessTokenstring required
tokenTypestring
expiresIninteger required
expiresAtinteger required
issuedAtinteger required
targetUserIdstring required
targetEmailstring required
targetNamestring nullable
actorEmailstring required
mode'full' | 'readonly' required

Changes

No recorded changes to this endpoint across all 1 revision of this API.