Share:
ClickHelp Documentation

User Management

With the user management functions, you can automate many operations related to setting up Restricted Access to your documentation portal. Available operations are documented below.

User Management Functions List

Create a Power Reader

Creates a new Power Reader user account with the specified parameters.

POST /api/v1/users HTTP/1.1

Parameters

Field Type Description
userName String (required)

The login name of the Power Reader user to be created.

userInfo Object (required)

User profile information object.

  email String (required) 

User e-mail address.

  firstName

String (required) 

User first name.

middleName String  User middle name.
  lastName String  User last name.
userRole String One or more Power Reader roles (comma-separated). Roles define the reader's permissions. If the role is not specified, the Power Reader will not be able to access any publications until you set up this user's permissions manually in your ClickHelp portal.
isDontSendEmail Boolean Defines whether the user will get an e-mail with the automatically generated password. Note that passwords are not stored in the system in plain text due to security considerations. So if you set this parameter to true, the user will not be able to access the system until the password is reset by an administrator or restored via the Forgot Password link on the login page.

Request Example

Below, is an example of a CURL command line you can use in a batch file to create a new Power Reader.

curl -X POST ^
--basic ^
--user administrator:t62dVG0YkqdTHO4G4K7z2jQ8 ^
--header "Content-Type:application/json" ^
-d "{ \"userName\": \"NewPowerReader\", \"userInfo\": {\"email\": \"power-reader@company.co\", \"firstName\": \"John\", \"middleName\": \"M\", \"lastName\": \"Doe\"}, \"userRole\": \"Role1\", \"isDontSendEmail\": false}" ^
--cacert comodo.ca-bundle ^
https://doc.clickhelp.co/api/v1/users

Response Codes

All API functions may return error codes listed in the Error Handling topic. Below, are the operation-specific meanings of some response codes:

  • 201 (Created)
    A new Power Reader account has been successfully created.
    The response body is empty.
  • 409
    User creation failed - a user with the same name already exists.

Read Power Reader Data

Retrieves information on a Power Reader with the specified user name.

Information If you need to obtain information on publications available to the given Power Reader, see solutionhere.

GET /api/v1/users/{userName} HTTP/1.1

Request Example

Below, is an example of a CURL command line you can use in a batch file to get the profile data of a Power Reader.

curl -X GET ^
--basic ^
--user administrator:t62dVG0YkqdTHO4G4K7z2jQ8 ^
--cacert comodo.ca-bundle ^
https://doc.clickhelp.co/api/v1/users/NewPowerReader

Response Fields

Field Type Description
userName String

The login name of the Power Reader.

userInfo Object

User profile information object.

  email String

User e-mail address.

  firstName

String

User first name.

middleName String  User middle name.
  lastName String  User last name.
userRole String

One or more Power Reader Roles (comma-separated) that define the permissions and the ability to access specific Publications for the reader.


Note: Even if this value is null, it is still possible that the user has access permissions assigned directly and can access some publications. Currently, information on such permissions cannot be retrieved via API and available in the application's UI only.

isEnabled Boolean True if the user account is enabled and the user can log in to the portal.

Response Example

{
"userName":"john.doe",

"userInfo": { "email":"someone@example.com", "firstName":"John", "middleName":"M",
"lastName":"Doe" }, "userRole": null, "isEnabled": true }

Response Codes

All API functions may return error codes listed in the Error Handling topic. Below, are the operation-specific meanings of some response codes:

  • 200 (OK)
    Returned if the information was retrieved successfully.
    Response body contains the data.
  • 400
    Returned if the specified user is not a Power Reader.
  • 404
    Returned if a user with the specified name does not exist.

Change a Power Reader Profile

Updates a Power Reader user profile.

PATCH /api/v1/users/{userName} HTTP/1.1

Parameters

Field Type Description
updatedFields String

A comma-separated list of field names which will be updated. If a field name is not in the list, it will not be updated even if the field value is specified in other request parameters.

email String

User e-mail address.

userRole String

The Power Reader Role which defines the permissions.

isEnabled Boolean Defines whether the user account is enabled and the user is allowed to log in to the portal.

Request Example

Below, is an example of a CURL command line you can use in a batch file to change the role assigned to a Power Reader.

curl -X PATCH ^
--basic ^
--user administrator:t62dVG0YkqdTHO4G4K7z2jQ8 ^
--header "Content-Type:application/json" ^
-d "{\"updatedFields\": \"userRole\", \"userRole\": \"Role2\"}" ^
--cacert comodo.ca-bundle ^
https://doc.clickhelp.co/api/v1/users/NewPowerReader

Response Codes

All API functions may return error codes listed in the Error Handling topic. Below, are the operation-specific meanings of some response codes:

  • 200 (OK)
    Returned if no user properties were updated.
  • 204 (No Content)
    Returned if the changes have been applied successfully. Response body is empty.
  • 400
    Returned if the specified user is not a Power Reader.
  • 404
    Returned if a user with the specified user name does not exist.

Getting One-Time Authentication Tokensa 

One-time authentication tokens can be used to implement a custom authentication scheme when standard SSO is not an option, but it is necessary to bypass the ClickHelp login screen and seamlessly authenticate users of a third-party application or website in ClickHelp.

A token is a unique string which can be specified as a Login page URL parameter to log in as a specific Power Reader just once. Tokens are created per your request and each token has an expiration date which you specify when creating the token. For security reasons, we recommend that you generate tokens only when a user is going to access the ClickHelp portal and set small expiration intervals for the tokens.

Here is how a token can be retrieved for a Power Reader:

GET /api/v1/users/{userName}/tokens?exp={expirationDate} HTTP/1.1

Parameters

Field Type Description
userName String The login name of the Power Reader.
expirationDate String
Token expiration date: timestamp string in the ISO 8601 format, in the GMT
timezone. Optional. The default value is 30 minutes ahead of the current moment. 

Request Example

Below, is an example of a CURL command line you can use in a batch file to get the token for a Power Reader.

curl -X GET ^
--basic ^
--user administrator:t62dVG0YkqdTHO4G4K7z2jQ8 ^
--cacert comodo.ca-bundle ^
https://doc.clickhelp.co/api/v1/users/NewPowerReader/tokens?exp=2020-12-07T12:11:47Z

Response Fields

Field Type Description
userName
String The login name of the Power Reader.
token
String The one-time login token that can be used to authenticate the Power Reader.
expirationDate
String
The date and time of the moment when the token will expire in the ISO 8601 format (UTC).

Response Example

{
"userName": "john.doe",
"token": "kjshd78Dkljod66DsD0Ddsal2l33pa1d",
"expirationDate": "2020-12-07T12:11:47Z"
}

Response Codes

All API functions may return error codes listed in the Error Handling topic. Below, are the operation-specific meanings of some response codes:
  • 200 (OK)
    The request has succeeded, the response body contains the requested information.
  • 400
    Returned if the specified user is not a Power Reader.
  • 403
    Returned if the authenticated user does not have permission to generate login tokens.
  • 404
    Returned if a user with the specified name does not exist.
  • 409
    Returned if the expiration date specified as a parameter is in the past.