Book a demo

impersonate_user

Sign in as a customer's user

act entity tenant-private since 2026-10-01

Staff operations, holding an active act grant to the org, signs in as one of its members to see what they see, for a number of minutes (thirty unless said, at most four hours). The answer carries a one-time sign-in link once Clerk has issued it: read it with get_impersonation until status is ready. The impersonated session shows a banner on every screen, every act in it is recorded as staff acting as the user, and it ends when the minutes pass or the grant ends. A member who holds a staff role cannot be impersonated.

Contract

shape
entity
authority
act
evidence
none
subscription
false
permission
any one of: staff.break_glass (staff.ops held in the Internal org, tradehq_role.staff_role, by a person the TRA-318 adoption logged as break-glass in tradehq_role.staff_role_log: Sage and Sonja only); a deactivated caller is refused first
idempotency
keyed
emits
session.impersonated
MCP tool
none
decision_set
approve, reject
REST
POST https://api.containertradehq.com/v1/cap/impersonate_user

Idempotency: keyed by the caller's Idempotency-Key, which is required: the same key and inputs replay the first result, the same key with other inputs is 409 idempotency_key_reused

Inputs

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org the caller holds an act grant to, and the user is a member of.
user_iduser_idrequiredtradehq-user-id; 1 to 20 characters
The member to sign in as.
reasontextrequired1 to 500 characters
Why, recorded with every act the session makes.
minutesintegeroptional5 to 240; default 30
How long the impersonated session may last: thirty minutes unless said.

Response

  • impersonation_id · string · The impersonation.
  • org_id · string · The org it is in.
  • user_id · string · Who is impersonated.
  • grant_id · string · The act grant that allows it.
  • status · string · pending until the link is issued, then ready; failed, expired or ended.
  • sign_in_url · stringnull · The one-time sign-in link, while status is ready: answered by get_impersonation alone, never by impersonate_user. Open it in a private window.
  • token_expires_at · stringnull · When the link stops working.
  • session_expires_at · string · When the impersonated session ends.
  • failed · stringnull · Why the link could not be issued, when it could not.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "impersonation_id": {
      "type": "string",
      "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$",
      "format": "uuid",
      "description": "The impersonation.",
      "x-data-class": "operational"
    },
    "org_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The org it is in.",
      "x-data-class": "operational"
    },
    "user_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "Who is impersonated.",
      "x-data-class": "operational"
    },
    "grant_id": {
      "type": "string",
      "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$",
      "format": "uuid",
      "description": "The act grant that allows it.",
      "x-data-class": "operational"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "ready",
        "failed",
        "expired",
        "ended"
      ],
      "description": "pending until the link is issued, then ready; failed, expired or ended.",
      "x-data-class": "operational"
    },
    "sign_in_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "The one-time sign-in link, while status is ready: answered by get_impersonation alone, never by impersonate_user. Open it in a private window.",
      "x-data-class": "operational"
    },
    "token_expires_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When the link stops working.",
      "x-data-class": "operational"
    },
    "session_expires_at": {
      "type": "string",
      "format": "date-time",
      "description": "When the impersonated session ends.",
      "x-data-class": "operational"
    },
    "failed": {
      "type": [
        "string",
        "null"
      ],
      "description": "Why the link could not be issued, when it could not.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "impersonation_id",
    "org_id",
    "user_id",
    "grant_id",
    "status",
    "sign_in_url",
    "token_expires_at",
    "session_expires_at",
    "failed"
  ],
  "additionalProperties": false
}

Refusals

The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.

Surfaces

DesktopF
MobileN
APIF
MCPN
VoiceD6
PushF
OneBoxN
OutboundN
  • Mobile: D6: the impersonated session opens in a browser on a desktop
  • MCP: the answer carries a one-time sign-in link, which is never handed to an agent
  • Voice: degraded: authority
  • OneBox: no document originates an impersonation
  • Outbound: crosses to no counterparty

Events

Related

break_glass_access, grant_unit_role, list_sessions, list_unit_access, request_staff_grant, revoke_sessions, revoke_unit_role, set_member_role, suspend_org