Users API

GET /api/v1/users/me

curl -X GET "https://your-domain.com/api/v1/users/me" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "code": 0,
  "data": {
    "id": "3f2a1b0c-9d8e-4f7a-8b6c-5d4e3f2a1b0c",
    "username": "johndoe",
    "email": "john.doe@example.com",
    "is_active": true,
    "approval_status": "approved",
    "is_superuser": false,
    "email_verified": true,
    "avatar_url": "https://example.com/avatars/johndoe.png",
    "locale": "en",
    "created_at": "2026-01-15T10:00:00Z",
    "last_login": "2026-09-24T14:30:00Z",
    "auth_source": "local",
    "external_id": null,
    "force_password_change": false,
    "password_expiration_exempt": false,
    "status": "active",
    "roles": [
      {
        "id": "9d8e4f7a-8b6c-4d5e-a1f2-3b4c5d6e7f80",
        "name": "user",
        "description": null,
        "is_system_role": true,
        "permissions": []
      }
    ],
    "sso_connections": [
      {
        "id": "4d5e6f70-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
        "provider_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "provider_name": "github",
        "provider_display_name": "GitHub",
        "provider_icon_url": null,
        "provider_user_id": "12345678",
        "provider_username": "johndoe",
        "provider_email": "john.doe@example.com",
        "first_login": "2026-02-01T08:00:00Z",
        "last_login": "2026-09-24T14:30:00Z"
      }
    ]
  },
  "msg": "success"
}

PUT /api/v1/users/me

curl -X PUT "https://your-domain.com/api/v1/users/me" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "johnsmith", "locale": "en"}'

POST /api/v1/users/me/change-password

curl -X POST "https://your-domain.com/api/v1/users/me/change-password" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"current_password": "OldPassword123!", "new_password": "NewPassword456!"}'

{ "code": 0, "data": null, "msg": "Password changed successfully" }

GET /api/v1/users/me/password-status

{
  "code": 0,
  "data": {
    "is_exempt": false,
    "password_changed_at": "2026-06-01T08:00:00+00:00",
    "password_expires_at": "2026-08-30T08:00:00+00:00",
    "is_expired": false,
    "days_until_expiration": 12,
    "force_change_required": false
  },
  "msg": "success"
}

DELETE /api/v1/users/me

{ "password": "CurrentPassword123!" }

curl -X DELETE "https://your-domain.com/api/v1/users/me" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"password": "CurrentPassword123!"}'

GET /api/v1/admin/users

curl -X GET "https://your-domain.com/api/v1/admin/users?page=1&page_size=20&status=pending" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

GET /api/v1/admin/users/stats

{
  "code": 0,
  "data": { "total": 156, "active": 150, "inactive": 2, "pending": 4 },
  "msg": "success"
}

GET /api/v1/admin/users/{user_id}

POST /api/v1/admin/users

curl -X POST "https://your-domain.com/api/v1/admin/users" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "email": "alice@example.com", "password": "SecurePassword123"}'

PUT /api/v1/admin/users/{user_id}

DELETE /api/v1/admin/users/{user_id}

POST /api/v1/admin/users/{user_id}/activate
POST /api/v1/admin/users/{user_id}/deactivate

POST /api/v1/admin/users/send-email

curl -X POST "https://your-domain.com/api/v1/admin/users/send-email" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Maintenance notice", "content": "The system is down on Saturday.", "user_ids": ["3f2a1b0c-9d8e-4f7a-8b6c-5d4e3f2a1b0c"]}'

{
  "code": 0,
  "data": { "sent_count": 1, "skipped_count": 0, "total": 1 },
  "msg": "Emails have been queued for sending"
}

POST /api/v1/admin/users/{user_id}/force-password-change

POST /api/v1/admin/users/{user_id}/reset-password-expiration

POST /api/v1/admin/users/{user_id}/exempt-password-expiration

{ "exempt": true }

POST /api/v1/admin/users/bulk-force-password-change

{ "user_ids": ["3f2a1b0c-...", "9d8e4f7a-..."] }

GET /api/v1/admin/users/password-expiration-stats

GET /api/v1/admin/users/expiring-passwords?page=1&page_size=20&filter=expiring

import os
import requests

BASE = "https://your-domain.com/api/v1"


def get_password_status(token: str) -> dict:
    """Check password status so you can warn before expiry."""
    response = requests.get(
        f"{BASE}/users/me/password-status",
        headers={"Authorization": f"Bearer {token}"},
    )
    result = response.json()
    if result["code"] != 0:
        raise RuntimeError(f"{result['code']} {result['msg']}")
    return result["data"]


def change_password(token: str, current_password: str, new_password: str) -> None:
    """Change the current user's password."""
    response = requests.post(
        f"{BASE}/users/me/change-password",
        headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
        json={"current_password": current_password, "new_password": new_password},
    )
    result = response.json()
    if result["code"] != 0:
        # on 1001, data.errors.new_password lists the policy reasons
        raise RuntimeError(f"{result['code']} {result['msg']} {result.get('data')}")


def bulk_send_email(admin_token: str, subject: str, content: str, user_ids: list[str]) -> dict:
    """Send bulk email as an administrator; returns queue statistics."""
    response = requests.post(
        f"{BASE}/admin/users/send-email",
        headers={"Authorization": f"Bearer {admin_token}", "Content-Type": "application/json"},
        json={"subject": subject, "content": content, "user_ids": user_ids},
    )
    result = response.json()
    if result["code"] != 0:
        raise RuntimeError(f"{result['code']} {result['msg']}")
    return result["data"]


# Usage
token = os.environ["USER_TOKEN"]
status = get_password_status(token)
print(f"password expires in {status['days_until_expiration']} days")

const BASE = 'https://your-domain.com/api/v1';

async function getCurrentUser(token) {
  const response = await fetch(`${BASE}/users/me`, {
    headers: { Authorization: `Bearer ${token}` },
  });
  const result = await response.json();
  if (result.code !== 0) throw new Error(`${result.code} ${result.msg}`);
  return result.data;
}

async function updateProfile(token, { username, locale, avatarUrl } = {}) {
  const response = await fetch(`${BASE}/users/me`, {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ username, locale, avatar_url: avatarUrl }),
  });
  const result = await response.json();
  if (result.code !== 0) throw new Error(`${result.code} ${result.msg}`);
  return result.data;
}

async function setUserActive(adminToken, userId, active) {
  const action = active ? 'activate' : 'deactivate';
  const response = await fetch(`${BASE}/admin/users/${userId}/${action}`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${adminToken}` },
  });
  const result = await response.json();
  if (result.code !== 0) throw new Error(`${result.code} ${result.msg}`);
  return result.data;
}

// Usage
const token = process.env.USER_TOKEN;
const user = await getCurrentUser(token);
console.log('user:', user.username);