Create impersonation session request
POST/tenants/{tenant_id}/impersonations
Creates a new admin impersonation session request for a tenant, targeting a specific user account. Requires admin password re-confirmation (current_password), a support ticket reference, and a stated reason. Scope determines the access level granted. Depending on platform configuration, the session may require a second admin to approve before a start_url is issued.
Request
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
tenant_id | string | Yes | The tenant identifier. |
Request body
Content type application/json (required).
| Field | Type | Required | Description |
|---|---|---|---|
target_user_id | integer | Yes | ID of the tenant user account to impersonate (must be a valid user in the tenant's user table). Minimum: 1 |
scope | string | Yes | Access scope to request — always use the minimum scope necessary. One of: |
reason | string | Yes | Business justification for the impersonation (displayed in the audit log and approval queue). Max length: 2000 |
ticket_ref | string | Yes | Support or incident ticket reference that authorises this access. Max length: 120 |
notes | string, nullable | No | Additional context for the approver. Max length: 2000 |
current_password | string | Yes | The requesting admin's current password for re-authentication confirmation. Min length: 6 |
Example
{
"target_user_id": 12,
"scope": "readonly",
"reason": "Customer reported incorrect invoice total — investigating billing module state.",
"ticket_ref": "SUP-2026-0042",
"notes": "Customer confirmed they have not made any changes since the issue appeared.",
"current_password": "AdminPassword2026!"
}Responses
201 Impersonation session created. If auto-approval is configured, the response includes an impersonation_start_url. Otherwise, a second admin must approve via the /approve endpoint
Content type application/json, object · ImpersonationSessionResponseV1.
| Field | Type | Required | Description |
|---|---|---|---|
session_id | string | No | Unique identifier for the created or approved session. |
status | string | No | Current status of the session. One of: |
impersonation_start_url | string, nullable | No | Time-limited URL the requesting admin uses to enter the tenant workspace. Null while the session is still pending approval. The URL contains a single-use signed token that expires after 15 minutes. |
message | string | No | Human-readable outcome message. |
Example
{
"session_id": "imp_01HXN8K2V3PABC",
"status": "pending",
"impersonation_start_url": null,
"message": "Impersonation request created and awaiting approval."
}401 current_password is incorrect
404 Tenant or target_user_id not found
422 Validation failed — check scope enum, ticket_ref, or reason length
Example request
Paths are relative to the control-plane API base URL ($BASE_URL below).
curl -X POST "$BASE_URL/tenants/{tenant_id}/impersonations" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"target_user_id": 12, "scope": "readonly", "reason": "Customer reported incorrect invoice total — investigating billing module state.", "ticket_ref": "SUP-2026-0042", "notes": "Customer confirmed they have not made any changes since the issue appeared.", "current_password": "AdminPassword2026!"}'