# API Reference

## List Users

Retrieves a list of all users for the current account.

* **URL**: `/Users`
* **Method**: `GET`
* **Response**:
  * **Code**: 200 OK
  * **Content**:

    ```json
    {
      "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
      "totalResults": <integer>,
      "Resources": [
        {
          "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
          "id": "<string>",
          "userName": "<string>",
          "name": {
            "formatted": "<string>",
            "givenName": "<string>",
            "familyName": "<string>"
          },
          "emails": [
            {
              "primary": true,
              "value": "<string>",
              "type": "work"
            }
          ],
          "active": <boolean>,
          "roles": [<string>]
        },
        // ... more users
      ]
    }
    ```

## Get User

Retrieves a specific user by their SCIM ID or external ID.

* **URL**: `/Users/:id`
* **Method**: `GET`
* **URL Parameters**: `id=[string]` (SCIM ID or external ID)
* **Response**:
  * **Code**: 200 OK
  * **Content**: Same as individual user object in List Users response

## Create User

Creates a new user in the system.

* **URL**: `/Users`
* **Method**: `POST`
* **Data Params**:

  ```json
  {
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "id": "<string>"
    "userName": "<string>",
    "name": {
      "givenName": "<string>",
      "familyName": "<string>"
    },
    "emails": [
      {
        "value": "<string>",
        "primary": true,
        "type": "work"
      }
    ],
    "externalId": "<string>",
    "active": <boolean>,
    "roles": {
      "admin": <boolean>,
      "member": <boolean>,
      "editor": <boolean>
    }
  }
  ```
* **Response**:
  * **Code**: 201 Created
  * **Content**: Created user object

## Update User

Updates an existing user's information.

* **URL**: `/Users/:id` (SCIM ID or external ID)
* **Method**: `PUT`
* **URL Parameters**: `id=[string]` ( ID or external ID)
* **Data Params**: Same as Create User
* **Response**:
  * **Code**: 200 OK
  * **Content**: Updated user object

#### 5. Delete User

Deletes a user from the system.

* **URL**: `/Users/:id`
* **Method**: `DELETE`
* **URL Parameters**: `id=[string]` ( ID or external ID)
* **Response**:
  * **Code**: 204 No Content

## Error Responses

In case of errors, the API will respond with an appropriate HTTP status code and a JSON object containing error details:

```json
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "detail": "<string>",
  "status": "400"
}
```

Common error scenarios:

* User not found: 404 Not Found
* Invalid input: 422 Unprocessable Entity
* Attempting to delete account owner: 403 Forbidden
* Internal server error: 500 Internal Server Error

### Notes

* The API uses SCIM 2.0 schemas and conventions.
* User passwords are automatically generated and not returned in responses.
* The `active` field in user objects indicates whether the user account is currently active.
* The `roles` field in user objects contains an object with role names as keys and boolean values indicating whether the role is assigned to the user within the current account.

#### Overriding Roles

When creating or updating a user, you can override the default roles by including a `roles` object in your request. The `roles` object should contain boolean values for each role you want to set:

```json
"roles": {
  "admin": false,
  "member": true,
  "editor": false
}
```

* If you don't include the `roles` object, the default roles will be applied (admin: false, member: true, editor: false).
* If you include the `roles` object but omit a role, it will be set to `false` by default.
* To assign a role to a user, set its value to `true` in the `roles` object.
* To remove a role from a user, set its value to `false` in the `roles` object.

Example:

```json
{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "john.doe@example.com",
  "name": {
    "givenName": "John",
    "familyName": "Doe"
  },
  "emails": [
    {
      "value": "john.doe@example.com",
      "primary": true,
      "type": "work"
    }
  ],
  "active": true,
  "roles": {
    "admin": true,
    "member": true,
    "editor": false
  }
}
```

This request would create a user with both admin and member roles, but without the editor role.

* When creating or updating users, email validation is skipped to accommodate various SCIM client behaviors.
* The account owner cannot be deleted through this API.