API Reference

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 IDcreateUser

Authentication

BearerAuth·http bearer·API key token (envoy_<hex>). Create keys from Settings → API Keys — see Using the API.

Request body

This request body is required.

Content typeapplication/json

requestobject

2 properties

usernamestringrequired

rolestring

Default: viewer
Allowed values: admin, viewer

Success response body

201User created with invite token

User created with invite token

Content typeapplication/json

responseobject

8 properties

idinteger

usernamestring

rolestring

Allowed values: superadmin, admin, viewer

totp_verifiedinteger

Allowed values: 0, 1

invite_pendingboolean

created_atstring · date-time

updated_atstring · date-time

invite_tokenstring

One-time invite token (48h expiry)

Error responses

400Validation error

Validation error

Content typeapplication/json

responseobject

2 properties

errorstring

Example: NOT_FOUND

messagestring

Example: Resource not found

Example response

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

403Insufficient permissions

Insufficient permissions

No response content schema is documented.

Code examples

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

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);