Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mgpass.net/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The mgPass User Management API provides full CRUD operations on user accounts. All endpoints require admin authentication with the mgpass:admin scope.

​
Create a User

curl -X POST https://auth.mgpass.net/api/users \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "kwame@example.com",
    "password": "SecureP@ssw0rd",
    "name": "Kwame Asante",
    "phone": "+233241234567"
  }'

​
Get a User

Retrieve a user by ID, including their assigned roles: 
curl https://auth.mgpass.net/api/users/usr_abc123 \
  -H "Authorization: Bearer ADMIN_TOKEN"
Response: 
{
  "id": "usr_abc123",
  "email": "kwame@example.com",
  "name": "Kwame Asante",
  "phone": "+233241234567",
  "avatar": null,
  "gender": null,
  "date_of_birth": null,
  "address": null,
  "is_suspended": false,
  "created_at": 1711900000,
  "updated_at": 1711900000,
  "roles": [
    { "id": "role_subscriber", "name": "subscriber" }
  ]
}

​
Update a User

Update profile fields with a PATCH request. Only include the fields you want to change. 
curl -X PATCH https://auth.mgpass.net/api/users/usr_abc123 \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kwame Asante-Mensah",
    "phone": "+233551234567",
    "gender": "male",
    "date_of_birth": "1990-05-15"
  }'

​
Updatable Fields

FieldTypeDescription
namestringDisplay name
emailstringEmail address
phonestringPhone number (E.164 format)
avatarstringAvatar URL
genderstringGender
date_of_birthstringDate of birth (YYYY-MM-DD)
addressstringPhysical address

​
Search and List Users

List users with pagination and search: 
curl "https://auth.mgpass.net/api/users?page=1&limit=20&q=kwame" \
  -H "Authorization: Bearer ADMIN_TOKEN"
ParameterTypeDescription
pageintegerPage number (default: 1)
limitintegerResults per page (default: 20, max: 100)
qstringSearch by name or email

​
Suspend / Unsuspend

Suspended users cannot sign in or obtain new tokens. Existing sessions are revoked on suspension. 
# Suspend
curl -X POST https://auth.mgpass.net/api/users/usr_abc123/suspend \
  -H "Authorization: Bearer ADMIN_TOKEN"

# Unsuspend
curl -X POST https://auth.mgpass.net/api/users/usr_abc123/unsuspend \
  -H "Authorization: Bearer ADMIN_TOKEN"

​
Delete a User

Soft-deletes a user. The record is retained but the user can no longer sign in. 
curl -X DELETE https://auth.mgpass.net/api/users/usr_abc123 \
  -H "Authorization: Bearer ADMIN_TOKEN"
Deletion is a soft delete — the user record is marked as deleted but not removed from the database. Active sessions are revoked immediately.

​
User Sessions

View and manage a user’s active sessions: 
# List sessions
curl https://auth.mgpass.net/api/users/usr_abc123/sessions \
  -H "Authorization: Bearer ADMIN_TOKEN"

# Revoke all sessions
curl -X POST https://auth.mgpass.net/api/users/usr_abc123/sessions/revoke-all \
  -H "Authorization: Bearer ADMIN_TOKEN"

​
Social Identities

View a user’s linked social accounts: 
curl https://auth.mgpass.net/api/users/usr_abc123/identities \
  -H "Authorization: Bearer ADMIN_TOKEN"

​
Login History

View recent authentication events for a user: 
curl https://auth.mgpass.net/api/users/usr_abc123/login-history \
  -H "Authorization: Bearer ADMIN_TOKEN"

​
User Roles

Assign and remove roles from users: 
# Assign a role
curl -X POST https://auth.mgpass.net/api/users/usr_abc123/roles \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "role_id": "role_premium" }'

# Remove a role
curl -X DELETE https://auth.mgpass.net/api/users/usr_abc123/roles/role_premium \
  -H "Authorization: Bearer ADMIN_TOKEN"
See RBAC for details on roles and scopes.