Admin API

This endpoint requires admin-level roles (platform_admin or super_admin).

User Impersonation

Securely impersonate users for support and debugging purposes.

Overview

Impersonation allows authorized administrators to act as another user while maintaining full audit trails. This is essential for:

• Customer support troubleshooting
• Debugging user-reported issues
• Testing user-specific configurations
• Verifying permission setups

---

Security Model

Security Implications

User impersonation grants full access to another user's account and data. All impersonation sessions are audit-logged, require MFA, and should only be used for legitimate support purposes. Misuse of impersonation privileges may result in immediate termination and legal action.

Requirement	Description
Role Required	platform_admin or support_admin
MFA Required	Yes, must have active MFA
Audit Logging	All actions logged with impersonator context
Time Limited	Sessions expire after 1 hour
Scope Limited	Cannot impersonate higher-privilege users

---

Start Impersonation

Request

POST /api/v1/auth/impersonate/start
Authorization: Bearer {admin_access_token}
Content-Type: application/json

{
  "target_user_id": "550e8400-e29b-41d4-a716-446655449122",
  "reason": "Customer reported issue with order placement - ticket #45678"
}

Parameters

Field	Type	Required	Description
target_user_id	UUID	Yes	User to impersonate
reason	string	No	Reason for impersonation (logged)

Response

{
  "impersonation_id": "uuid-of-impersonation-session",
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2g...",
  "impersonated_user": {
    "id": "550e8400-e29b-41d4-a716-446655449122",
    "email": "staff@demo-restaurant.com",
    "name": "Server User",
    "roles": ["pos_staff"]
  },
  "expires_at": "2026-01-18T11:30:00Z"
}

---

End Impersonation

Request

POST /api/v1/auth/impersonate/{session_id}/end
Authorization: Bearer {admin_access_token}

Parameter	Type	Required	Description
session_id	UUID	Yes	The impersonation session ID (returned from start)

Response

{
  "impersonation_id": "uuid-of-impersonation-session",
  "ended_at": "2026-01-18T10:44:07Z",
  "original_session_restored": true
}

---

Impersonation Token

The impersonation token contains special claims in addition to standard JWT claims:

{
  "sub": "user-123",
  "tid": "tenant-uuid",
  "roles": ["pos_staff"],
  "impersonation_id": "imp-session-uuid",
  "admin_user_id": "admin-uuid",
  "original_session_id": "admin-original-session-uuid",
  "exp": 1737203400
}

Claim	Description
impersonation_id	Impersonation session identifier
admin_user_id	Original admin user performing impersonation
original_session_id	Admin's original session to restore

---

Restrictions

During impersonation, certain actions are blocked:

Blocked Action	Reason
Change password	Security
Enable/disable MFA	Security
Update billing	Financial security
Delete account	Irreversible
Impersonate others	Prevent chaining
Access other tenants	Scope limitation

---

Get Active Impersonation

Check if the current admin user has an active impersonation session.

Request

GET /api/v1/auth/impersonate/active
Authorization: Bearer {admin_access_token}

Response

Returns the active ImpersonationSession object if one exists, or null.

{
  "id": "session-uuid",
  "admin_user_id": "admin-uuid",
  "impersonated_user_id": "user-uuid",
  "tenant_id": "tenant-uuid",
  "original_session_id": "original-session-uuid",
  "impersonation_session_id": "imp-session-uuid",
  "reason": "Investigating ticket #45678",
  "started_at": "2026-01-18T10:30:00Z",
  "ended_at": null,
  "is_active": true
}

---

List Impersonation History

Request

GET /api/v1/auth/impersonate/history?limit=50&offset=0
Authorization: Bearer {admin_access_token}

Query Parameters

Parameter	Type	Default	Description
limit	integer	50	Maximum number of records to return
offset	integer	0	Number of records to skip

Response

Returns an array of ImpersonationSession objects:

[
  {
    "id": "session-uuid",
    "admin_user_id": "admin-uuid",
    "impersonated_user_id": "user-uuid",
    "tenant_id": "tenant-uuid",
    "original_session_id": "original-session-uuid",
    "impersonation_session_id": "imp-session-uuid",
    "reason": "Investigating ticket #45678",
    "started_at": "2026-01-18T10:30:00Z",
    "ended_at": "2026-01-18T10:44:07Z",
    "is_active": false
  }
]

---

Error Responses

Insufficient Permissions (403)

{
  "error": {
    "code": "IMPERSONATION_NOT_ALLOWED",
    "message": "You do not have permission to impersonate users"
  }
}

Target User Protected (403)

{
  "error": {
    "code": "TARGET_USER_PROTECTED",
    "message": "Cannot impersonate users with higher privileges"
  }
}

MFA Required (403)

{
  "error": {
    "code": "MFA_REQUIRED",
    "message": "MFA must be enabled to use impersonation"
  }
}

Reason Required (400)

{
  "error": {
    "code": "REASON_REQUIRED",
    "message": "A reason must be provided for impersonation"
  }
}

---

UI Indicators

When impersonating, the UI should clearly indicate:

┌─────────────────────────────────────────────────────────────┐
│ ⚠️ IMPERSONATING: Jane Doe (customer@restaurant.com)        │
│    Reason: Ticket #45678 | Expires in 45:23 | [End Session] │
└─────────────────────────────────────────────────────────────┘

---

Best Practices

1. Always provide clear reasons - Helps with audit and compliance
2. Use minimum duration - Request only the time needed
3. Avoid sensitive actions - Don't access financial or personal data unnecessarily
4. Document findings - Update support tickets with findings
5. End sessions promptly - Don't leave impersonation sessions open

---

Code Examples

Start Impersonation

# Start an impersonation session (requires admin JWT)
RESP=$(curl -s -X POST https://dev.api.olympuscloud.ai/v1/auth/impersonate/start \
  -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target_user_id": "550e8400-e29b-41d4-a716-446655449122",
    "reason": "Investigating ticket #45678"
  }')
IMP_TOKEN=$(echo $RESP | jq -r '.access_token')
IMP_ID=$(echo $RESP | jq -r '.impersonation_id')

# Use the impersonation token to perform actions as the user
curl https://dev.api.olympuscloud.ai/v1/commerce/orders \
  -H "Authorization: Bearer $IMP_TOKEN"

# End the impersonation session
curl -X POST "https://dev.api.olympuscloud.ai/v1/auth/impersonate/$IMP_ID/end" \
  -H "Authorization: Bearer $ADMIN_ACCESS_TOKEN"

---

Related Documentation

• Authentication Overview - Authentication concepts
• Sessions - Session management
• Security Best Practices - Security guide