Provisioning Users With The API

This tutorial will walk you through using the Help Lightning API to provision new users in your Help Lightning site.

Please make sure you have read through both the Partner Key Setup and the API Keys.

You will need:

• An Authorization Token (We Recommend using a Partner Key.
• API Key
• curl

All examples will be done using the command line tool curl to make requests to the Help Lightning API.

To provision a user, we will use the invite_user_to_enterprise route, which is located at /api/v1r1/enterprise/users. The previous link includes all the parameters and response type for this API. Note, that not all parameters are required!

In this example, we are going to assume that our site is set up to use Single Sign-on (SSO). We also don’t want to have Help Lightning send a welcome email, as our users will be informed about the service in a different manner.

Help Lightning has two data centers: US and Europe. These both contain the same APIs, but you will need to make sure you are using the correct URL based upon which data center your site is located in:

• US :: https://api.helplightning.net
• Europe :: https://api.eu1.helplightning.net

Make sure you have an API Key and an Authorization Token. We will be provisioning a user with the following attributes:

• Name: John Doe
• Email: john.doe@example.com
• Role: User (default)
• Don’t sent an email

We will set three HTTP headers:

1. Authorization :: Include your authorization token
2. x-helplightning-api-key :: Include your api key
3. content-type :: Set this to application/json to indicate you will be sending a JSON payload.

This example is using the US data center. If you are using the Europe data center, please make sure you update the Base URL

$ curl -X POST \
       https://api.helplightning.net/api/v1r1/enterprise/users \
       -H 'Authorization: your-token-here' \
       -H 'x-helplightning-api-key: your-api-key-here' \
       -H 'content-type: application/json' \
       -d '{"name": "John Doe", "email": "john.doe@example.com", "role": "User", "send_email": false}'

At this point, the user has been created and will be able to log into Help Lightning with their SSO credentials!

In the previous example, we did not specify any groups (also called pods in the API). The provisioned users were just placed in the default group. This may be ok, but if you have a complex organization structure, you might consider grouping your users.

It is possible to specify a list of group ids when provisioning a user, however, how do you get those ids?

There are two ways:

1. You can log into the Help Lightning web interface as an administrator, go to Admin -> Groups, click on the details of a group, then find the id in the URL. For example, if the URL is https://helplightning.net/admin/workspace/groups/31627, then this groups id is 31627.
2. You can also use the API to get a list of the groups.

This is a tutorial on using the API, so let’s get the groups programatically. The API is straight forward, we don’t require any parameters other than the required headers:

$ curl -X GET \
       https://api.helplightning.net/api/v1r1/enterprise/pods \
       -H 'Authorization: your-token-here' \
       -H 'x-helplightning-api-key: your-api-key-here' \
       -H 'content-type: application/json' \

This will return an output similar to:

{
  "entries": [
    {
      "id": 3566,
      "enterprise_id": 3423,
      "name": "Group 1",
      "description": "Group 1 Description",
      "avatar": {
        "original": "https://helplightning.net/avatars/3566/full.jpg",
        "thumb": "https://helplightning.net/avatars/3566/thumb.jpg"
      },
      "default": true,
      "user_count": 10,
      "admin_count": 0,
      "subpods": [
      ],
      "admins": [
      ]
    },
    {
      "id": 3568,
      "enterprise_id": 3423,
      "name": "Group 2",
      "description": "Group 2 Description",
      "avatar": {
        "original": "https://helplightning.net/avatars/3568/full.jpg",
        "thumb": "https://helplightning.net/avatars/3568/thumb.jpg"
      },
      "default": false,
      "user_count": 4,
      "admin_count": 0,
      "subpods": [
      ],
      "admins": [
      ]
    }
  ],
  "total_entries": 2,
  "total_pages": 1,
  "page": 1,
  "page_size": 20
}

We can iterate through the entries and find the ids of the desired groups.

The results of this API are paginated. If you have more groups than your page size, you will need to iterate through, passing in a new ?page=X to the URL.

Let’s provision another user and this time, put the user in both of our groups (3566 and 3568):

$ curl -X POST \
       https://api.helplightning.net/api/v1r1/enterprise/users \
       -H 'Authorization: your-token-here' \
       -H 'x-helplightning-api-key: your-api-key-here' \
       -H 'content-type: application/json' \
       -d '{"name": "Jane Doe", "email": "jane.doe@example.com", "role": "User", "send_email": false, pod_ids: [3566,3568]}'

The new user (Jane Doe) should be in both groups!

When an employee leaves your organization, you will often want to unprovision them and remove their access to Help Lightning. There are two ways to do this:

1. Deactivate a User
2. Delete a User

When you deactivate a user, that user will no longer able to log in or use Help Lightning. However, all their data will remain available. This is useful for shared data like call history. A deactivated user does not use any of your licenses, and you can reactive a user at any time.

If you delete a user, you will remove all that user’s data from the Help Lightning system. If there was any shared data (calls, comments) that reference this user, they will now reference a special ‘Deleted User’. This operation cannot be undone!

We first need to find the user we want to deactivate. We can use the API for this. It is possible to iterate through all our users using the get_enterprise_users route, however, we can also apply a filter based upon the email addres.

In this example, we are going to lookup our John Doe user by their email: john.doe@example.com and get their information.

It is very important to Percent Encode your query parameters in the filter or they may not be interpreted correctly!

The filter is a complex filter. In this case, we are going to ask it to filter on the email field and that we want an exact match to john.doe@example.com. This would look like filter=email=john.doe@example.com, however, this needs to be Percent Encoded to filter=email%3Djohn.doe%40example.com where we changed the = to %3D and the @ to %40. This will be a query parameter appended to our URL.

$ curl -X GET \
       https://api.helplightning.net/api/v1r1/enterprise/users?filter=email%3Djohn.doe%40example.com \
       -H 'Authorization: your-token-here' \
       -H 'x-helplightning-api-key: your-api-key-here' \
       -H 'content-type: application/json' \

This will hopefully return a single result that looks something like (truncated for brevity):

{
  "entries": [
    {
      "id": 374523,
      "username": "john.doe1",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "available": true,
      "last_used_at": "2019-08-24T14:15:22Z",
      ...
      "active": true,
    }
  ],
  "total_entries": 1,
  "total_pages": 1,
  "page": 1,
  "page_size": 20
}

Our user’s id is 374523.

To deactivate a user, we are going to do a PUT operation on the user using the update_enterprise_user (/api/v1r1/enterprise/users/:user_id) route. We only need to include parameters in the body that we want to change. In this case, we are going to set the active parameter to false.

Notice the ID of the user we are operating on is part of the URL.

$ curl -X PUT \
       https://api.helplightning.net/api/v1r1/enterprise/users/374523 \
       -H 'Authorization: your-token-here' \
       -H 'x-helplightning-api-key: your-api-key-here' \
       -H 'content-type: application/json' \
       -d '{"active": false}'

This user has now been deactivated and cannot login. To reverse this change, make the same call, but set active to true.

To delete a user from the system, we are going to issue a DELETE operation on the user using the remove_user_from_enterprise (/api/v1r1/enterpriser/users/:user_id) route. We do not need to include any parameters.

This operation CANNOT be undone!

Notice the ID of the user we are operating on is part of the URL.

$ curl -X DELETE \
       https://api.helplightning.net/api/v1r1/enterprise/users/374523 \
       -H 'Authorization: your-token-here' \
       -H 'x-helplightning-api-key: your-api-key-here' \
       -H 'content-type: application/json'

The user has no been removed from Help Lightning’s system.