fastify-xadmin

Impersonation Routes

Start and end admin impersonation sessions — POST /api/admin/users/:id/impersonate and DELETE /api/admin/impersonate.

Impersonation Routes

Allow admins to temporarily log in as any user for support and debugging. Impersonation issues a short-lived JWT scoped to the target user. Ending an impersonation session restores the original admin context.

Routes

POST   /api/admin/users/:id/impersonate   Start an impersonation session
DELETE /api/admin/impersonate             End the current impersonation session

POST /api/admin/users/:id/impersonate

Generate an impersonation JWT that authenticates as the specified user. Use the returned token in subsequent requests to act on that user's behalf.

Usage

const response = await fetch(`/api/admin/users/${userId}/impersonate`, {
  method: "POST",
  headers: { Authorization: `Bearer ${adminToken}` },
});
const { token, expiresAt } = await response.json();

Path Parameters

Name	Type	Required	Description
`id`	`string`	Yes	ID of the user to impersonate.

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "userId": "usr_123",
  "expiresAt": "2025-04-19T13:00:00.000Z"
}

Field	Type	Description
`token`	`string`	Short-lived JWT to use as `Authorization: Bearer <token>` in impersonated requests.
`userId`	`string`	ID of the user being impersonated.
`expiresAt`	`string`	ISO 8601 expiry timestamp.

Notes

The impersonation JWT has a short TTL (typically 1 hour) and cannot be refreshed.
The start event is recorded in the Audit Log.
Superadmins cannot be impersonated to prevent privilege escalation.

DELETE /api/admin/impersonate

End the active impersonation session for the current admin. Invalidates the impersonation token.

Usage

await fetch("/api/admin/impersonate", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${impersonationToken}` },
});

Response

{ "ended": true }

Example — Full impersonation workflow

// 1. Start impersonation
const { token } = await fetch(`/api/admin/users/${targetUserId}/impersonate`, {
  method: "POST",
  headers: { Authorization: `Bearer ${adminToken}` },
}).then((r) => r.json());

// 2. Make requests as the target user
const profile = await fetch("/api/me", {
  headers: { Authorization: `Bearer ${token}` },
}).then((r) => r.json());

console.log("Viewing as:", profile.email);

// 3. End the session when done
await fetch("/api/admin/impersonate", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${token}` },
});

AI Context

package: "@xenterprises/fastify-xadmin"
routes:
  - POST /api/admin/users/:id/impersonate — issues short-lived impersonation JWT for target user
  - DELETE /api/admin/impersonate — invalidates the impersonation token
audit: start and end events are recorded in the audit log
security: superadmins cannot be impersonated; tokens are short-lived and non-renewable
auth: requires the admin role set at plugin registration