Appearance
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)
| Field | Type | Required |
|---|---|---|
| reason | string | Yes |
| ttl_seconds | integer | No |
| user_id | string | Yes |
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
| Status | Code | Detail |
|---|---|---|
| 400 | reason must be at least 3 characters | Invalid Request; Invalid Request; Invalid Request; Invalid Request |
| 400 | request body must be valid JSON | Invalid Request; Invalid Request; Invalid Request; Invalid Request |
| 400 | ttl_seconds must be between 1 and 900 | Invalid Request; Invalid Request; Invalid Request; Invalid Request |
| 400 | user_id is required | Invalid Request; Invalid Request; Invalid Request; Invalid Request |
| 401 | authentication failed | Unauthorized |
| 403 | insufficient_permissions | Forbidden; Step-up Required; Forbidden; Forbidden; Forbidden; Forbidden |
| 403 | self-impersonation is not allowed | Forbidden; Step-up Required; Forbidden; Forbidden; Forbidden; Forbidden |
| 403 | service accounts cannot be impersonated | Forbidden; Step-up Required; Forbidden; Forbidden; Forbidden; Forbidden |
| 403 | step_up_required | Forbidden; Step-up Required; Forbidden; Forbidden; Forbidden; Forbidden |
| 403 | the target user is not eligible for impersonation | Forbidden; Step-up Required; Forbidden; Forbidden; Forbidden; Forbidden |
| 403 | the target user must be active | Forbidden; Step-up Required; Forbidden; Forbidden; Forbidden; Forbidden |
| 404 | the requested resource was not found | Not Found |
| 409 | idempotency_in_progress | Idempotency In Progress |
| 422 | idempotency_conflict | Idempotency Conflict |
| 500 | authentication service unavailable | Internal Server Error |