Skip to content
Torii docs

Mint an impersonation token

POST
/api/server/v1/users/{userId}/impersonation-token
 
curl --request POST \
  --url https://api.torii.so/api/server/v1/users/01931a73-8b00-7000-8000-000000000000/impersonation-token \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "actorUserId": "01931a73-8b00-7000-8000-000000000000", "reason": "Investigating support ticket #4821", "redirectUrl": "https://app.example.com/dashboard", "expiresInSeconds": 600 }'

Creates a single-use, short-lived impersonation token for the target user, attributed to actorUserId. Redeem it programmatically via POST /_torii/auth/session/impersonate (access token in the body), or hand the returned url to an operator to open in a browser (establishes the session and redirects to the landing URL). Counts against the same per-period impersonation quota and usage ledger as the dashboard.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
userId
required
string format: uuid

The user to impersonate.

Example 
01931a73-8b00-7000-8000-000000000000

Request Body required

Section titled “Request Body required ”
Media type application/json

Body for minting an impersonation token.

object
actorUserId
required

The principal the impersonation is on behalf of (recorded for accountability). Must be a user in this environment.

string format: uuid
Example 
01931a73-8b00-7000-8000-000000000000
reason
required

Mandatory justification (GDPR purpose limitation); recorded in the audit log on mint and redeem.

string
0 <= 500 characters
Example 
Investigating support ticket #4821
redirectUrl

Optional post-redeem landing URL for the url redeem link; its origin must be in the environment’s allowed origins. Omit to default to the environment’s first non-wildcard allowed origin.

string | null
Example 
https://app.example.com/dashboard
expiresInSeconds

Optional token lifetime in seconds, 60..600. Omit for the 600s default.

integer | null format: int64
>= 60 <= 600
Example 
600

Responses

Section titled “ Responses ”

200

Section titled “200 ”

The minted token, its lifetime, and (when a landing URL resolves) a ready-to-use redeem URL.

Media type application/json

A minted impersonation token.

object
token
required

The single-use token. Redeem via POST /_torii/auth/session/impersonate, or hand the ready-to-use url to an operator.

string
expiresInSeconds
required

The token’s lifetime in seconds (the resolved value after any override).

integer format: int64
url

A ready-to-use, navigable redeem link on the environment’s Frontend API host. Opening it in a browser establishes the impersonated session and redirects to the landing URL. Backed by the same single-use token. Null when no landing URL could be resolved (no redirectUrl given and the environment has no concrete allowed origin) — redeem the token via POST instead.

string | null
Example 
{
  "expiresInSeconds": 600,
  "url": "https://auth.example.com/_torii/auth/session/impersonate?token=…"
}

400

Section titled “400 ”

Deleted target, expiresInSeconds out of the 60..600 range, or redirectUrl missing/malformed/not in the environment’s allowed origins.

Media type application/problem+json
object
type
string format: uri
title
string
status
integer format: int32
detail
string
instance
string format: uri
properties
object
key
additional properties
Example generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com",
  "properties": {
    "additionalProperty": "example"
  }
}

401

Section titled “401 ”

Missing or invalid secret key.

Media type application/problem+json
object
type
string format: uri
title
string
status
integer format: int32
detail
string
instance
string format: uri
properties
object
key
additional properties
Example generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com",
  "properties": {
    "additionalProperty": "example"
  }
}

402

Section titled “402 ”

Plan does not include impersonation, or the per-period quota is exhausted.

Media type application/problem+json
object
type
string format: uri
title
string
status
integer format: int32
detail
string
instance
string format: uri
properties
object
key
additional properties
Example generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com",
  "properties": {
    "additionalProperty": "example"
  }
}

403

Section titled “403 ”

Target or actor is in another environment, or impersonation is disabled for this environment.

Media type application/problem+json
object
type
string format: uri
title
string
status
integer format: int32
detail
string
instance
string format: uri
properties
object
key
additional properties
Example generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com",
  "properties": {
    "additionalProperty": "example"
  }
}