List tenant impersonation sessions

GET/tenants/{tenant_id}/impersonations

Returns the most recent impersonation sessions for the specified tenant, including approved, active, and terminated sessions. Use to audit support access history and ensure all impersonation activity is justified and documented.

Request

Path parameters

Name	Type	Required	Description
tenant_id	string	Yes	The tenant identifier (subdomain slug, e.g. "acme").

Query parameters

Name	Type	Required	Description
status	string	No	Filter sessions by status. One of: "pending", "approved", "active", "terminated", "expired"
limit	integer	No	Maximum number of sessions to return. Default: 10

Responses

200 List of impersonation sessions for the tenant

Content type application/json, array of object · TenantImpersonationSessionV1.

Field	Type	Required	Description
id	string	No	Unique session identifier.
tenant_id	string	No	The tenant this session targets.
target_user_id	integer	No	ID of the tenant user account being impersonated.
scope	string	No	Access scope granted to the impersonating admin. "readonly" — view-only access with no write operations. "limited_write" — can submit specific support actions only. "full_user" — full access as the impersonated user (highest risk; requires additional approval). One of: "readonly", "limited_write", "full_user"
reason	string	No	Stated reason for the impersonation, required for audit.
ticket_ref	string	No	Support or incident ticket reference number.
notes	string, nullable	No	Additional context notes attached to the session.
status	string	No	Current lifecycle status of the session. One of: "pending", "approved", "active", "terminated", "expired"
created_by_admin	string	No	Email address of the admin who requested the session.
approved_by_admin	string, nullable	No	Email of the second admin who approved the session (null if not yet approved).
approved_at	string (date-time), nullable	No
terminated_at	string (date-time), nullable	No
created_at	string (date-time)	No

Example

[
  {
    "id": "imp_01HXN8K2V3PABC",
    "tenant_id": "acme",
    "scope": "readonly",
    "reason": "Customer reported incorrect invoice total — investigating billing module state.",
    "ticket_ref": "SUP-2026-0042",
    "status": "terminated",
    "created_by_admin": "admin@faciotech.com",
    "approved_at": "2026-04-08T10:05:00Z",
    "terminated_at": "2026-04-08T10:47:00Z"
  }
]

404 Tenant not found

Example request

Paths are relative to the control-plane API base URL ($BASE_URL below).

curl -X GET "$BASE_URL/tenants/{tenant_id}/impersonations" \
  -H "Accept: application/json"