GameCraftGameCraft
API ReferenceSystem Admin

List Users

Get a list of all users (system admin only)

List Users

Get a paginated list of all users in the system. This endpoint requires system admin authentication.

Authentication

Required: System Admin Secret Key

Authorization: Bearer $SYSTEM_ADMIN_API_SECRET_KEY

This endpoint uses the global system admin secret key, not user API keys. The SYSTEM_ADMIN_API_SECRET_KEY must be configured in your environment variables.

Endpoint

GET /api/v1/system-admin/users

Query Parameters

ParameterTypeRequiredDefaultDescription
limitnumberNo20Number of users per page (max: 100)
offsetnumberNo0Pagination offset
searchstringNo-Search by email or name
rolestringNo-Filter by role: USER or ADMIN

Response

Success (200)

{
  "users": [
    {
      "id": "usr_abc123",
      "name": "John Doe",
      "email": "john@example.com",
      "emailVerified": true,
      "role": "USER",
      "banned": false,
      "image": "https://example.com/avatar.jpg",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Unauthorized (401)

{
  "error": "Invalid system admin secret key"
}

Examples

cURL

curl -X GET "http://localhost:3000/api/v1/system-admin/users?limit=10" \
  -H "Authorization: Bearer $SYSTEM_ADMIN_API_SECRET_KEY"
curl -X GET "http://localhost:3000/api/v1/system-admin/users?search=john&role=USER" \
  -H "Authorization: Bearer $SYSTEM_ADMIN_API_SECRET_KEY"

Python

import os
import requests

SITE_API_KEY = os.environ['SYSTEM_ADMIN_API_SECRET_KEY']
BASE_URL = 'http://localhost:3000/api/v1'

headers = {
    'Authorization': f'Bearer {SITE_API_KEY}'
}

response = requests.get(
    f'{BASE_URL}/system-admin/users',
    params={'limit': 10, 'offset': 0},
    headers=headers
)

data = response.json()
for user in data['users']:
    print(f"{user['email']} - {user['role']}")

TypeScript/JavaScript

const SITE_API_KEY = process.env.SYSTEM_ADMIN_API_SECRET_KEY;

const response = await fetch('http://localhost:3000/api/v1/system-admin/users?limit=10', {
  headers: {
    'Authorization': `Bearer ${SITE_API_KEY}`
  }
});

const data = await response.json();
console.log(`Total users: ${data.total}`);

Use Cases

Microservice Integration

Use this endpoint to:

  • Sync user data between services
  • Build administrative dashboards
  • Generate system-wide reports
  • Audit user activity across services

Security Considerations

  1. Never expose the SYSTEM_ADMIN_API_SECRET_KEY to clients
  2. Only use this endpoint in server-to-server communication
  3. Rotate the secret key regularly
  4. Monitor usage for unauthorized access attempts

See Also

On this page