> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chamelio.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create User

> Create a new user in your organization with a specified role.

## Endpoint

```
POST /users
```

## Authentication

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

```bash theme={null}
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

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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);
  ```
</CodeGroup>

## Response

### Success Response

**Status Code:** `200 OK`

```json theme={null}
{
  "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.

```json theme={null}
{
  "detail": "User with this email already exists"
}
```

### 401 Unauthorized

Returned when authentication fails. See the [authentication errors](/api-reference/introduction#authentication-errors) section for details.

```json theme={null}
{
  "detail": "Invalid API key"
}
```

### 422 Unprocessable Entity

Returned when the request body fails validation.

```json theme={null}
{
  "detail": "Validation error"
}
```

### 500 Internal Server Error

Returned when the user could not be created due to a server error.

```json theme={null}
{
  "detail": "Failed to create user"
}
```

## Notes

<Info>
  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.
</Info>

## 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