Create User

Create a new user account in the organization.

POST /api/v1/users
Authentication
Bearer Token
Version
v1
Section
Users
Tags
users write

Create a new user within your organization. The new user will receive a welcome email (unless sendInvite is set to false).

Request Headers

HeaderTypeRequiredDescription
Authorization*string✓Bearer token with users:write scope.
Content-Type*string✓Must be application/json.

Request Body

Content-Type: application/json

User creation payload.

{
  "name": "Bob Johnson",
  "email": "bob@example.com",
  "roles": ["editor"],
  "sendInvite": true
}
FieldTypeRequiredDescription
name*string✓Full name of the user.
email*string✓Valid email address. Must be unique within the organization.
rolesarray[string]—Initial roles to assign. Defaults to ["viewer"].
sendInviteboolean—Whether to send a welcome email. Default: true.

Responses

StatusDescription
201User created successfully.
{
  "id": "usr_xyz789",
  "name": "Bob Johnson",
  "email": "bob@example.com",
  "roles": ["editor"],
  "createdAt": "2025-01-15T09:00:00Z"
}
400Validation error — check errors in response body.
409A user with this email already exists.

Examples

curl -X POST "https://api.example.com/v1/users" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bob Johnson",
    "email": "bob@example.com",
    "roles": ["editor"]
  }'

const res = await fetch('/api/v1/users', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Bob Johnson',
    email: 'bob@example.com',
    roles: ['editor']
  })
});
const newUser = await res.json();

import requests

r = requests.post(
    'https://api.example.com/v1/users',
    headers={'Authorization': 'Bearer YOUR_TOKEN'},
    json={
        'name': 'Bob Johnson',
        'email': 'bob@example.com',
        'roles': ['editor']
    }
)
new_user = r.json()