Exchange workspace impersonation session (v1)

Method & Path

POST /api/v1/workspace/sessions/impersonation

Backend path: POST /v1/workspace/sessions/impersonation

Description

Exchanges a one-time token created by Create workspace impersonation login token for a standard workspace-owner access token and workspace payload (same shape as successful POST /v1/workspace/sessions login without MFA).

The one-time token is consumed on success and cannot be reused.

Persona access

Persona	Access
Public	Yes (no auth; requires valid unexpired unused token)
Admin / Staff / Customer	N/A

Authentication

None (the request body carries the secret).

Headers

Content-Type: application/json

Request Body

{
  "token": "opaque-one-time-token-from-admin-endpoint"
}

Field	Type	Required	Description
token	string	Yes	Single-use impersonation token

Response 200 OK

Same as owner login success: includes token (workspace JWT) and workspace object.

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "workspace": {
    "id": "...",
    "email": "owner@example.com",
    "name": null,
    "planId": "...",
    "businessCategorySlug": "...",
    "marketingOptIn": false,
    "branding": {},
    "security": { "mfaRequired": false, "allowedMfaMethods": [], "phoneOtpChannel": "sms", "updatedAt": null }
  }
}

Common Errors

• 400 Bad Request: Missing or empty token
• 401 Unauthorized: Invalid, expired, or already used token
• 404 Not Found: Workspace no longer exists
• 422 Unprocessable Entity: Validation failed