Admin and Moderator APIs

1. Create an Admin/Moderator

This API is used to create a new Admin or Moderator.

1.1. Request

URI (3.x, deprecated in 4.0.0)

POST /system/user

URI (4.x)

POST /api/system/user

Table 1. Request Body

user [Object] Required

The user object.

user.id [UUID] Optional

The Id of the user. If omitted an Id will be generated automatically.

user.applicationIds [Array<UUID>] Optional

The applications identifiers assigned to this user. If none are provided the user will have access to all applications in CleanSpeak.

user.email [String] Required

The email address of the user.

user.expirationInstantUTC [Long] Optional

The instants this user will expire and will be unable to login to CleanSpeak.

user.externalId [String] Optional

The external identifier used to link this user to another system.

user.password [String] Required

The password for the user.

user.roles [Array<String>] Optional

The roles to be assigned to the user. The possible values are:

  • admin

  • approve_all

  • audit_viewer

  • filter

  • filter_manager

  • moderator

  • moderator_manager

  • user_admin

  • webhook_manager Available since 3.27.0

Example Request JSON
{
  "user" : {
    "applicationIds": [
      "6ea8f201-4a7f-47f4-900a-862234c54dd1"
    ],
    "email" : "moderator@example.com",
    "password": "super-secret-password",
    "roles" : [
      "admin"
    ]
  }
}

1.2. Response

Table 2. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.

500

There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 3. Response Body

user [Object]

The user object.

user.id [UUID]

The Id of the user.

user.applicationIds [Array<UUID>]

The applications identifiers assigned to this user. If none are present the user will have access to all applications in CleanSpeak.

user.email [String]

The email address of the user.

user.expirationInstantUTC [Long]

The instants this user will expire and will be unable to login to CleanSpeak.

user.externalId [String]

The external identifier used to link this user to another system.

user.roles [Array<String>]

The roles assigned to the user. The possible values are:

  • admin

  • approve_all

  • audit_viewer

  • filter

  • filter_manager

  • moderator

  • moderator_manager

  • user_admin

  • webhook_manager Available since 3.27.0

Example Response JSON
{
  "user" : {
    "applicationIds": [
      "6ea8f201-4a7f-47f4-900a-862234c54dd1"
    ],
    "email" : "moderator@example.com",
    "id" : "c4be9117-8cb9-46bb-b805-0f0e612cd0c6",
    "roles" : [
      "admin"
    ]
  }
}

2. Retrieve an Admin/Moderator

This API is used to retrieve an existing Admin or Moderator.

2.1. Request

URI (3.x, deprecated in 4.0.0)

GET /system/user/{userId}

URI (4.x)

GET /api/system/user/{userId}

Table 4. Request Parameters

userId [UUID] Required

The Id of the User to retrieve.

2.2. Response

Table 5. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.

404

The object you requested doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 6. Response Body

user [Object]

The user object.

user.id [UUID]

The Id of the user.

user.applicationIds [Array<UUID>]

The applications identifiers assigned to this user. If none are present the user will have access to all applications in CleanSpeak.

user.email [String]

The email address of the user.

user.expirationInstantUTC [Long]

The instants this user will expire and will be unable to login to CleanSpeak.

user.externalId [String]

The external identifier used to link this user to another system.

user.roles [Array<String>]

The roles assigned to the user. The possible values are:

  • admin

  • approve_all

  • audit_viewer

  • filter

  • filter_manager

  • moderator

  • moderator_manager

  • user_admin

  • webhook_manager Available since 3.27.0

3. Update an Admin/Moderator

This API is used to update an existing Admin or Moderator.

3.1. Request

URI (3.x, deprecated in 4.0.0)

PUT /system/user/{userId}

URI (4.x)

PUT /api/system/user/{userId}

Table 7. Request Parameters

userId [UUID] Required

The Id of the User to update.

Table 8. Request Body

user [Object] Required

The user object.

user.applicationIds [Array<UUID>] Optional

The applications identifiers assigned to this user. If none are provided the user will have access to all applications in CleanSpeak.

user.email [String] Required

The email address of the user.

user.expirationInstantUTC [Long] Optional

The instants this user will expire and will be unable to login to CleanSpeak.

user.externalId [String] Optional

The external identifier used to link this user to another system.

user.password [String] Optional

The password for the user. If omitted the password will not be changed.

user.roles [Array<String>] Optional

The roles to be assigned to the user. The possible values are:

  • admin

  • approve_all

  • audit_viewer

  • filter

  • filter_manager

  • moderator

  • moderator_manager

  • user_admin

  • webhook_manager Available since 3.27.0

Example Request JSON
{
  "user" : {
    "applicationIds": [
      "6ea8f201-4a7f-47f4-900a-862234c54dd1"
    ],
    "email" : "moderator@example.com",
    "roles" : [
      "filter_manager",
      "moderator_manager"
    ]
  }
}

3.2. Response

Table 9. Response Codes
Code Description

200

The request was successful. The response will contain a JSON body.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.

404

The object you requested doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.

Table 10. Response Body

user [Object]

The user object.

user.id [UUID]

The Id of the user.

user.applicationIds [Array<UUID>]

The applications identifiers assigned to this user. If none are present the user will have access to all applications in CleanSpeak.

user.email [String]

The email address of the user.

user.expirationInstantUTC [Long]

The instants this user will expire and will be unable to login to CleanSpeak.

user.externalId [String]

The external identifier used to link this user to another system.

user.roles [Array<String>]

The roles assigned to the user. The possible values are:

  • admin

  • approve_all

  • audit_viewer

  • filter

  • filter_manager

  • moderator

  • moderator_manager

  • user_admin

  • webhook_manager Available since 3.27.0

Example Response JSON
{
  "user" : {
    "applicationIds": [
      "6ea8f201-4a7f-47f4-900a-862234c54dd1"
    ],
    "email" : "moderator@example.com",
    "id" : "c4be9117-8cb9-46bb-b805-0f0e612cd0c6",
    "roles" : [
      "filter_manager",
      "moderator_manager"
    ]
  }
}

4. Delete an Admin/Moderator

This API is used to delete a Admin or Moderator. When a user is deleted they are marked as disabled.

Once a user has been deleted, they may not be enabled through the use of an API. A deleted user can be enabled by a CleanSpeak admin user in the CleanSpeak Management Interface.

A deleted user cannot log into CleanSpeak, be retrieved using the Retrieve User API or be updated using the Update User API.

4.1. Request

URI (3.x, deprecated in 4.0.0)

DELETE /system/user/{userId}

URI (4.x)

DELETE /api/system/user/{userId}

Table 11. Request Parameters

userId [UUID] Required

The Id of the User to delete.

4.2. Response

Table 12. Response Codes
Code Description

200

The request was successful. The response will be empty.

400

The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.

401

You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.

402

Your license has expired. The response will be empty. Contact sales@cleanspeak.com for assistance.

404

The object you are trying to delete doesn’t exist. The response will be empty.

500

There was an internal error. A stack trace is provided and logged in the CleanSpeak log files. The response will be empty.