Book a demo

get_impersonation

Read an impersonation you started

read entity tenant-private since 2026-10-01

Answers an impersonation the caller started with impersonate_user, as it stands: pending until Clerk issues the one-time sign-in link, then ready with the link until it expires; failed, expired or ended otherwise. Call it until status is ready. Only the staff member who started the impersonation is answered; any other id is not found.

Contract

shape
entity
authority
read
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
safe
emits
none
MCP tool
none
REST
POST https://api.containertradehq.com/v1/cap/get_impersonation

Idempotency: a read: calling again changes nothing

Inputs

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org the impersonation is in.
impersonation_iduuidrequiredUUID
The impersonation, as impersonate_user answered it.

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
PushN
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
  • Push: emits nothing
  • OneBox: no document originates an impersonation
  • Outbound: crosses to no counterparty

Events

None emitted.

Related

None.