Create a user

POST /api/users

Creates a new user account with a one-time invite token. Superadmin can create admins and viewers. Admins can only create viewers. The invite token should be shared with the user so they can set their own password and enroll TOTP via /invite/{token}.

Operation ID: createUser

Authentication

Option 1

• BearerAuth (http bearer) API key token. Create via POST /api/api-keys. Format: envoy_<hex>

Option 2

• CookieAuth (apiKey) Session cookie set after login + TOTP verification

Request body

The request body is required.

application/json

• Type: object
• Properties:
  • username (string, required)
  • role (string)
    • Allowed values: admin, viewer
    • Default: viewer

Success responses

201

User created with invite token

Content type: application/json

• Type: UserSafe & object
• All of:
  • Variant 1:
    • Reference: UserSafe
      • Type: object
      • Properties:
        • id (integer)
        • username (string)
        • role (string)
          • Allowed values: superadmin, admin, viewer
        • totp_verified (integer)
          • Allowed values: 0, 1
        • invite_pending (boolean)
        • created_at (string)
          • Format: date-time
        • updated_at (string)
          • Format: date-time
  • Variant 2:
    • Type: object
    • Properties:
      • invite_token (string) — One-time invite token (48h expiry)

Error responses

400

Validation error

Content type: application/json

• Reference: Error
  • Type: object
  • Properties:
    • error (string)
      • Example: NOT_FOUND
    • message (string)
      • Example: Resource not found

Example:

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid input"
}

403

Insufficient permissions

Examples

cURL

curl --request POST \
  --url 'https://your-envoy.example.com/api/users' \
  --header 'Authorization: Bearer $API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "username": "string"
}'

JavaScript (fetch)

const response = await fetch('https://your-envoy.example.com/api/users', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "username": "string"
  }),
});
 
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = response.status === 204 ? null : await response.json();
console.log(data);