Skip to main content

​
Overview

Admin endpoints provide elevated privileges for platform administrators, including user impersonation for support and debugging.

​
POST /api/admin/impersonate

Generate impersonation token to access another user’s account.

​
Authentication

Requires admin-level Directus JWT token.

​
Request Body

​
userId
string
required
Directus user ID to impersonate
​
duration
number
Token duration in seconds (default: 3600)

​
Response

​
token
string
Temporary JWT token for impersonated user
​
expiresAt
string
ISO 8601 timestamp when token expires
​
user
object
Impersonated user’s profile data

​
Example

cURL
curl -X POST http://localhost:3001/api/admin/impersonate \
  -H "Authorization: Bearer ADMIN_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user-abc-123",
    "duration": 1800
  }'

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2026-03-04T13:30:00Z",
  "user": {
    "id": "user-abc-123",
    "email": "[email protected]",
    "first_name": "Jane",
    "role": "creator"
  }
}

​
Impersonation Use Cases

​
Customer Support

View user’s account as they see it:
  1. User reports dashboard issue
  2. Admin generates impersonation token
  3. Admin accesses user’s session in separate browser tab
  4. Investigate issue in live environment

​
Debugging

Reproduce tier-specific behavior:
  • Test feature availability for different tiers
  • Verify usage limit enforcement
  • Debug permission issues

​
Demo Accounts

Create pre-configured demo environments:
  • Generate tokens for demo accounts
  • Share with prospects during sales calls
  • Automatically expire after demo period

​
Security Considerations

Impersonation grants full access to user’s account. Use only when necessary and maintain audit logs.

​
Audit Trail

All impersonation actions logged to agent_audits collection: 
{
  "action": "admin_impersonate",
  "admin_user_id": "admin-123",
  "target_user_id": "user-456",
  "duration_seconds": 1800,
  "ip_address": "192.168.1.100",
  "user_agent": "Mozilla/5.0...",
  "timestamp": "2026-03-04T12:00:00Z"
}

​
Token Restrictions

  • Short-lived: Default 1 hour expiration
  • Single-use recommended: Generate new token for each session
  • IP binding: Optional IP address validation
  • Revocation: Tokens invalidated on user password change

​
Admin Permissions

Only users with Directus role administrator can impersonate: 
// Permission check in server/endpoints/api/impersonate.js
if (req.user.role.name !== 'administrator') {
  return res.status(403).json({ error: 'Forbidden' });
}

​
Dashboard Integration

Admin panel at /admin includes impersonation UI:
  1. User Search: Find users by email/name
  2. Quick Actions: One-click impersonation button
  3. Active Sessions: View currently impersonated users
  4. Session History: Past impersonation events

​
View-As Mode

/view-as route enables impersonation from dashboard: 
// Dashboard route: src/pages/ViewAs/index.jsx
<Route path="/view-as/:userId" element={<ViewAsMode />} />
Session stored in sessionStorage (not localStorage) to prevent persistence across browser restarts.

​
Implementation

Source: server/endpoints/api/impersonate.js Impersonation flow:
  1. Verify admin credentials via Directus /users/me
  2. Fetch target user data
  3. Generate temporary JWT with imp_ prefix
  4. Log action to agent_audits
  5. Return token for client storage
Impersonation tokens use same JWT secret as regular auth but include impersonator_id claim for audit tracking.

User Management

RBAC sync and user administration

Security

Security best practices and audit logging

Build docs developers (and LLMs) love

Get started for freeTalk to us