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_KEYThis 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/usersQuery Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
limit | number | No | 20 | Number of users per page (max: 100) |
offset | number | No | 0 | Pagination offset |
search | string | No | - | Search by email or name |
role | string | No | - | 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"With Search
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
- Never expose the
SYSTEM_ADMIN_API_SECRET_KEYto clients - Only use this endpoint in server-to-server communication
- Rotate the secret key regularly
- Monitor usage for unauthorized access attempts
Related Endpoints
- Get User Details - Get single user (user API key)
- Update User - Update user profile (user API key)