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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.screendesk.io/api/scim-autoprovisioning/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.