Skip to main content

Endpoint

POST /users

Authentication

This endpoint requires authentication via API key. Include your API key in the X-API-Key header:
X-API-Key: ca_your_api_key_here

Request Body

The request body must be a JSON object with the following fields:

Required Fields

FieldTypeDescription
emailstringEmail address of the new user
first_namestringFirst name of the new user

Optional Fields

FieldTypeDescription
last_namestringLast name of the new user. Defaults to an empty string
rolestringOrganization role to assign. One of admin, editor, member, viewer. Defaults to viewer
is_sso_userbooleanWhether the user authenticates via single sign-on (SSO). Defaults to false

Request Example

curl -X POST https://platform.chamelio.ai/users \
  -H "X-API-Key: ca_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new.user@example.com",
    "first_name": "New",
    "last_name": "User",
    "role": "editor",
    "is_sso_user": false
  }'
import requests

url = "https://platform.chamelio.ai/users"
headers = {
    "X-API-Key": "ca_your_api_key_here",
    "Content-Type": "application/json"
}
payload = {
    "email": "new.user@example.com",
    "first_name": "New",
    "last_name": "User",
    "role": "editor",
    "is_sso_user": False
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
const response = await fetch('https://platform.chamelio.ai/users', {
  method: 'POST',
  headers: {
    'X-API-Key': 'ca_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'new.user@example.com',
    first_name: 'New',
    last_name: 'User',
    role: 'editor',
    is_sso_user: false
  })
});

const data = await response.json();
console.log(data);

Response

Success Response

Status Code: 200 OK
{
  "user_id": 1003,
  "email": "new.user@example.com"
}

Response Fields

FieldTypeDescription
user_idintegerUnique identifier of the newly created user
emailstringEmail address of the newly created user

Error Responses

400 Bad Request

Returned when the request is invalid — for example, a malformed email or a user that already exists. The detail reflects the underlying validation error.
{
  "detail": "User with this email already exists"
}

401 Unauthorized

Returned when authentication fails. See the authentication errors section for details.
{
  "detail": "Invalid API key"
}

422 Unprocessable Entity

Returned when the request body fails validation.
{
  "detail": "Validation error"
}

500 Internal Server Error

Returned when the user could not be created due to a server error.
{
  "detail": "Failed to create user"
}

Notes

The new user is always created in the organization that owns the API key. The role defaults to viewer if omitted — set role explicitly to grant broader access.

Use Cases

This endpoint is useful for:
  • User provisioning - Programmatically onboard users from an external system
  • SSO onboarding - Pre-create SSO users so they can sign in via your identity provider
  • Role assignment - Create users with the appropriate organization role from the start