Endpoint
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
| Field | Type | Description |
|---|
email | string | Email address of the new user |
first_name | string | First name of the new user |
Optional Fields
| Field | Type | Description |
|---|
last_name | string | Last name of the new user. Defaults to an empty string |
role | string | Organization role to assign. One of admin, editor, member, viewer. Defaults to viewer |
is_sso_user | boolean | Whether 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
| Field | Type | Description |
|---|
user_id | integer | Unique identifier of the newly created user |
email | string | Email 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