Skip to content

Impersonation API Reference ​

POST /impersonations ​

Start an audited user impersonation

Use for time-bounded administrative support as an active user. Requires iam:impersonate:any and a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. The target must be active, must not be a service account or the caller, and must not hold effective IAM permissions. The required reason is recorded with the actor, target, TTL, token jti, and exact expires_at in the append-only audit log. The returned user-kind access token has no refresh token or session, carries act and imp claims, sets auth_time to zero, and cannot use MFA-only step-up or satisfy freshness guards.

Required permission — iam:impersonate:any Requires a user bearer with positive auth_time or step_up_time no older than ten minutes; timestamps up to 30 seconds in the future are accepted. Otherwise returns 403 step_up_required.

Request body (application/json) ​

FieldTypeRequired
reasonstringYes
ttl_secondsintegerNo
user_idstringYes
json
{
  "reason": "investigate support request",
  "ttl_seconds": 300,
  "user_id": "01J8Z3USER000000000000001"
}

Responses ​

  • 200 — Successful response
json
{
  "access_token": "signed-user-token",
  "expires_at": "2026-01-01T00:05:00Z",
  "token_type": "Bearer"
}

Errors ​

StatusCodeDetail
400reason must be at least 3 charactersInvalid Request; Invalid Request; Invalid Request; Invalid Request
400request body must be valid JSONInvalid Request; Invalid Request; Invalid Request; Invalid Request
400ttl_seconds must be between 1 and 900Invalid Request; Invalid Request; Invalid Request; Invalid Request
400user_id is requiredInvalid Request; Invalid Request; Invalid Request; Invalid Request
401authentication failedUnauthorized
403insufficient_permissionsForbidden; Step-up Required; Forbidden; Forbidden; Forbidden; Forbidden
403self-impersonation is not allowedForbidden; Step-up Required; Forbidden; Forbidden; Forbidden; Forbidden
403service accounts cannot be impersonatedForbidden; Step-up Required; Forbidden; Forbidden; Forbidden; Forbidden
403step_up_requiredForbidden; Step-up Required; Forbidden; Forbidden; Forbidden; Forbidden
403the target user is not eligible for impersonationForbidden; Step-up Required; Forbidden; Forbidden; Forbidden; Forbidden
403the target user must be activeForbidden; Step-up Required; Forbidden; Forbidden; Forbidden; Forbidden
404the requested resource was not foundNot Found
409idempotency_in_progressIdempotency In Progress
422idempotency_conflictIdempotency Conflict
500authentication service unavailableInternal Server Error