Admin API

Administrative endpoints for user impersonation and management

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
  }'

Example Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2026-03-04T13:30:00Z",
  "user": {
    "id": "user-abc-123",
    "email": "[e-mail]",
    "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.

Related Features

User Management

RBAC sync and user administration

Security

Security best practices and audit logging