Users

Attributes

  • id integer

    Unique identifier for the object.

  • username string

  • email string

  • phone

  • type string

    Either a type user or application, to keep track of API vs human consumers.

  • group string

    The name of the group this user is part of.

  • groupId string

    The ID to the group this user belongs to.

Endpoints

List Users

get /api/users

Get the list of users and return a JSON response.

Arguments

  • group string

    The user group this user belongs to (e.g. "Administrators" or "Supervisors").

  • userGroupId integer

    The ID assigned to the user group.

  • isAdmin boolean

    Either "true" or "false".

  • type string

    Either "user" or "application".

  • status integer

    The user's status. 0-pending, 1-active, 2-deactivated, 3-application

  • username string

    The name of the user account.

  • email string

    The email associated with the user account.

  • viewId integer

    The ID used for Dashboard views created by this user.

  • timeZone string

    The timezone chosen in the user's settings.

  • language string

    Either "en" or "fr".

  • limit integer

    A limit on the number of objects to be returned. Limit can range between 1 and 1000, and the default is 250.

  • offset integer

    Will return items, but only those after the integer amount.

  • countOnly boolean

    When true, will only return a count of the amount of items in the query.

Request with curl
curl "http://[Your IP] /api/users" \ -X get \ -H "Content-Type: application/json" \ -H "Authorization: Bearer [Your JWT Access Token]"
Example Response
{
    "users": [
        {
            "userGroupId": 1,
            "id": 1,
            "group": "Administrators",
            "isAdmin": true,
            "type": "user",
            "status": 1,
            "username": "{{Username}}",
            "email": "{{Email}}",
            "viewId": 1,
            "timeZone": "America/Toronto",
            "language": "en"
        },
        {
            "userGroupId": 1,
            "id": 2,
            "group": "Administrators",
            "isAdmin": true,
            "type": "application",
            "status": 3,
            "username": "{{Username}}",
            "email": null,
            "viewId": 2,
            "timeZone": null,
            "language": "en"
        },
        {
            "userGroupId": 2,
            "id": 3,
            "group": "Supervisors",
            "isAdmin": false,
            "type": "user",
            "status": 0,
            "username": "{{Username}}",
            "email": "{{Email}}",
            "viewId": 3,
            "timeZone": null,
            "language": "en"
        }
    ]
}

Create User

post /api/users

Create a user and get a response.

Body Parameters

  • username string REQUIRED

    The name of the user account.

  • password string REQUIRED

    Plaintext password (will be encoded in transit).

  • type string

    Either "user" or "application".

  • isAdmin boolean

    Either "true" or "false".

  • group string

    The user group this user belongs to (e.g. "Administrators" or "Supervisors").

  • userGroupId integer

    The ID assigned to the user group.

  • timeZone string

    The timezone chosen in the user's settings.

  • language string

    Either "en" (default) or "fr".

Request with curl
curl "http://[Your IP] /api/users" \ -X post \ -H "Content-Type: application/json" \ -H "Authorization: Bearer [Your JWT Access Token]" \
-d 'curl -L -X GET 'http://[Your IP/api/users' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer [Your JWT Access Token]'
--data-raw '{
	"username": "example",
    "email": "test@example.com",
	"password": "example",
	"type": "users",
    "userGroupId": 2
}''
Example Response
{
    "user": {
        "userGroupId": 2,
        "id": 10,
        "group": "Supervisors",
        "isAdmin": false,
        "type": "users",
        "status": 0,
        "username": "example",
        "email": "test@example.com",
        "viewId": null,
        "timeZone": null,
        "language": "en"
    }
}

Login User

post /api/users/login

In order to receive an access token, you must first login with your username and password passed in the body.

Save the returned access token and refresh token. When making an API request, include the access token in an authorization header of type Bearer.

After 15 minutes, the access token expire and a new one will need to be generated using the refresh token. (The expiry times for the access and refresh tokens are also returned in the response.)

Arguments

  • username string REQUIRED

    The username of the logged in user.

  • password string REQUIRED

    Plaintext password (will be encoded in transit).

Request with curl
curl "http://[Your IP] /api/users/login" \ -X post \ -H "Content-Type: application/json" \ -H "Authorization: Bearer [Your JWT Access Token]"
-d 'curl -L -X POST 'http://[Your IP]/api/users/login' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer [Your JWT Access Token]'
--data-raw '{
  "username": "{{Username}}",
  "password": "{{Password}}"
}''
Example Response
{
    "accessExpiryDate": "01/01/2022, 12:15:00",
    "id": 1,
    "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTY1MzA1NjMwNywianRpIjoi",
    "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTY1MzA1NjMwNywianRpIjoi",
    "isAdmin": "true",
    "username": "{{Username}}",
    "refreshExpiryDate": "01/31/2022, 12:00:00",
    "viewId": 1,
    "timeZone": null
}

Refresh Token

get /api/users/refresh

After 15 minutes, the access token will have expired and a new one will need to be generated. Include the Bearer Authorization header, but instead of using the access token, include the refresh token given to you when you first accessed the login endpoint. A new access token will be returned to you in the body. You can now use this token in the authorization header when making API requests.

After 30 days, the refresh token will expire. In order to generate a new refresh token, you must go through the login process again.

Arguments

Request with curl
curl "http://[Your IP] /api/users/refresh" \ -X get \ -H "Content-Type: application/json" \ -H "Authorization: Bearer [Your JWT Access Token]"
Example Response
{ "users": [{ "id": " integer ", "username": " string ", "email": " string ", "phone": " ", "type": " string ", "group": " string ", "groupId": " string ", }] }] }

Generate Application Token

post /api/users/application-token

If you would prefer to avoid having to refresh an expired token, you can generate an application token — a non-expiring access token.

Request with curl
curl "http://[Your IP] /api/users/application-token" \ -X post \ -H "Content-Type: application/json" \ -H "Authorization: Bearer [Your JWT Access Token]" \
-d 'curl -L -X POST 'http://[Your IP]/api/users/application-token' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer [Your JWT Access Token]''
Example Response
{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTY1MzA1NjMwNywianRpIjoi"
}