Skip to main content

​
Users

Manage API users and keys. All endpoints require admin authentication. 🔐

​
List Users

​
none
GET /users
List all API users.
curl -H "X-API-Key: your-admin-key" https://api.example.com/users

[
  {
    "user_id": "a1b2c3d4",
    "name": "Admin Dashboard",
    "email": "admin@example.com",
    "role": "admin",
    "is_active": true,
    "created_at": "2025-12-01T00:00:00.000Z",
    "updated_at": "2025-12-17T10:30:00.000Z",
    "usage": {
      "total_requests": 1523,
      "last_used_at": "2025-12-17T10:30:00.000Z",
      "first_used_at": "2025-12-01T00:00:00.000Z",
      "requests_today": 45,
      "last_reset": "2025-12-17T00:00:00.000Z"
    }
  }
]

​
Create User

​
none
POST /users
Create a new API user. Returns the API key (shown only once).

​
Request Body

​
name
string
required
Display name
​
email
string
Contact email
​
role
string
default:"user"
Either user or admin
curl -X POST https://api.example.com/users \
  -H "X-API-Key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Mobile App", "email": "app@example.com", "role": "user"}'

{
  "user": {
    "user_id": "x1y2z3w4",
    "name": "Mobile App",
    "email": "app@example.com",
    "role": "user",
    "is_active": true,
    "created_at": "2025-12-17T10:30:00.000Z",
    "updated_at": "2025-12-17T10:30:00.000Z",
    "usage": {
      "total_requests": 0,
      "requests_today": 0,
      "last_reset": "2025-12-17T10:30:00.000Z"
    }
  },
  "api_key": "abc123def456...",
  "warning": "Save this API key now. It cannot be retrieved again."
}
The api_key is only returned once on creation. Store it securely.

​
Get User

​
none
GET /users/:id
Get a user by ID.
curl -H "X-API-Key: your-admin-key" https://api.example.com/users/x1y2z3w4
Errors: 404 if user not found

​
Update User

​
none
PATCH /users/:id
Update user properties.

​
Request Body

​
name
string
Display name
​
email
string
Contact email
​
role
string
Either user or admin
​
is_active
boolean
Enable/disable the user
curl -X PATCH https://api.example.com/users/x1y2z3w4 \
  -H "X-API-Key: your-admin-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name", "is_active": false}'

​
Delete User

​
none
DELETE /users/:id
Delete a user and invalidate their API key.
curl -X DELETE -H "X-API-Key: your-admin-key" \
  https://api.example.com/users/x1y2z3w4

{
  "success": true,
  "deleted": "x1y2z3w4"
}

​
Rotate API Key

​
none
POST /users/:id/rotate-key
Generate a new API key. The old key is immediately invalidated.
curl -X POST -H "X-API-Key: your-admin-key" \
  https://api.example.com/users/x1y2z3w4/rotate-key

{
  "success": true,
  "api_key": "newkey789xyz...",
  "warning": "Save this API key now. It cannot be retrieved again."
}

​
Usage Tracking

Each user tracks API usage:
FieldDescription
total_requestsTotal API requests made
last_used_atTimestamp of most recent request
first_used_atTimestamp of first request
requests_todayRequests today (resets at midnight)
last_resetWhen daily counter was last reset