User Management
The AdminUserController provides full user lifecycle management -- searching, suspending, role assignment, deletion, and impersonation. These are the tools you will use daily as your SaaS grows: investigating support tickets, handling abuse reports, onboarding team members, and debugging user-reported issues.
Search and List Users
GET /api/admin/usersReturns a paginated list of all users. Supports search by name or email via query parameters.
GET /api/admin/users?search=john&page=1When to Use This
A user emails support saying they cannot log in. Search by their email address to find their account instantly. You can immediately see whether their account is suspended, whether their email is verified, when they last logged in, and which organizations they belong to. This turns a 10-minute investigation into a 10-second lookup.
Suspend and Unsuspend
POST /api/admin/users/{id}/suspend
POST /api/admin/users/{id}/unsuspendSuspended users are immediately logged out across all active sessions and cannot authenticate until unsuspended. The suspended_at timestamp is recorded on the user model.
When to Use This
A user is abusing your platform -- sending spam, violating your terms of service, or engaging in fraudulent activity. Suspend their account immediately. They are logged out everywhere, their API keys stop working, and they cannot log back in. This gives you time to investigate without the user continuing to cause damage.
If it turns out to be a misunderstanding -- maybe they triggered a rate limit accidentally or a teammate reported them by mistake -- simply unsuspend them. Their account is restored exactly as it was, with all their data and organization memberships intact. No data is lost during suspension.
Why This Matters
Every SaaS eventually deals with abuse. Having a one-click suspend button means you can respond in seconds, not hours. The fact that suspension is reversible makes it safe to act quickly and investigate later, rather than hesitating while a bad actor continues to abuse your platform.
Delete User
DELETE /api/admin/users/{id}When to Use This
A user submits a GDPR deletion request, or you need to remove a spam account permanently. This endpoint deletes the user and all associated data -- tokens, sessions, organization memberships, and personal information.
- Users with the
super_adminrole cannot be deleted through this endpoint. This is a safety measure that prevents accidental lockout -- you cannot accidentally delete the last admin account and lose access to your own platform. - All associated data (tokens, organization memberships, sessions) is cleaned up as part of the deletion.
- The deletion is recorded in the audit log for compliance purposes, including who deleted the account and when.
GDPR Compliance
Under GDPR, users have the right to request deletion of their personal data. This endpoint gives you a straightforward way to fulfill those requests. The audit log entry serves as your record that the deletion was performed, which you may need to demonstrate compliance to regulators.
Global Role Assignment
POST /api/admin/users/{id}/assign-role{
"role": "support_agent"
}POST /api/admin/users/{id}/remove-role{
"role": "support_agent"
}Global roles (super_admin, support_agent) are entirely separate from organization roles. Assigning a global role does not affect the user's membership in any organization, and removing it does not affect their organization access.
When to Use This
You hire a support person and need them to access the admin panel to look up user accounts and investigate issues. Assign them the support_agent role -- they get read-only access to the admin panel and can view users, organizations, settings, and audit logs, but they cannot modify anything. When they leave the company, remove the role and their admin access is instantly revoked.
Need to promote a trusted team member to full admin? Assign super_admin. Need to temporarily give someone admin access for a specific task? Assign the role, let them complete the task, then remove it.
Impersonation
POST /api/admin/users/{id}/impersonateGenerates a 1-hour scoped token that allows the admin to act as the target user. The admin sees exactly what the user sees -- their dashboard, their organizations, their data -- without needing to ask for the user's credentials.
When to Use This
A customer reports a bug you cannot reproduce. Instead of asking them to record a video, share their screen, or describe the problem in more detail, impersonate their account and see exactly what they see. You will be logged in as them, with their permissions, their data, and their organization context. This is the fastest way to debug user-reported issues.
Safety Measures
- 1-hour auto-expiry: The impersonation token expires automatically after 1 hour. You cannot accidentally stay logged in as another user indefinitely.
- Full audit trail: Every action taken while impersonating is logged in the audit trail. The log entries record both the impersonated user and the admin who initiated the impersonation, so you always have complete accountability.
- Admin identity preserved: The original admin's identity is stored in the audit metadata, so there is never any ambiguity about who actually performed an action.
Why This Matters
Impersonation is one of the most powerful support tools in a SaaS. It eliminates the back-and-forth of "can you send me a screenshot?" and "what browser are you using?" The 1-hour expiry and audit logging ensure it is safe to use -- your team has accountability, and there is no risk of an impersonation session being left open.
Stop Impersonating
POST /api/admin/impersonate/stopRevokes the impersonation token and returns the admin to their own session. You can also just let the token expire naturally after 1 hour.