API Reference

List Users

Retrieves a list of all users for the current account.

• URL: /Users

• Method: GET

• Response:

  • Code: 200 OK

  • Content:

    {
      "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:

  {
    "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:

{
  "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:

"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:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "[email protected]",
  "name": {
    "givenName": "John",
    "familyName": "Doe"
  },
  "emails": [
    {
      "value": "[email protected]",
      "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.