Users

Details about ItemPath users (not Power Pick).

Attributes

  • id integer

    Unique identifier for the user.

  • email string

    The email address associated with the user.

  • isAdmin boolean

    If the user is in the Admin group.

  • language string

    The user's set language.

    Possible values:

    en
    fr

  • roleId uuid

    The ID to the group this user belongs to.

  • roleName string

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

  • status integer

    The user's status.

    Possible values:

    0 = pending
    1 = active
    2 = deactivated
    3 = application

  • type string

    Used to keep track of API vs human consumers.

    Possible values:

    user
    application

  • username string

    The name of the user account.

  • viewId uuid

    The ID used for Dashboard views created by this user.

Endpoints

Login User /api/users/login
post

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.)

Body Parameters

  • 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://[subdomain.itempath.com or IP]/api/users/login" \ -X post \ -H "Content-Type: application/json" \
-d '{"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 /api/users/refresh
post

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.

Request with curl
curl "http://[subdomain.itempath.com or IP]/api/users/refresh" \ -X post \ -H "Content-Type: application/json" \ -H "Authorization: Bearer [Your JWT Refresh Token]" \ -d '{ }'
Example Response
{
    "accessExpiryDate": "01/01/2022, 12:15:00",
    "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTY1MzA1NjMwNywianRpIjoi",
    "id": 1,
    "refreshExpiryDate": "01/31/2022, 12:00:00",
    "refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTY1MzA1NjMwNywianRpIjoi",
    "username": "{{Username}}",
}
List Users /api/users
get

Get a list of ItemPath users. View the guide on adding filters to List API calls.

Body Parameters

  • roleId uuid

    The ID assigned to the user group.

  • status integer

    The user's status.

    Possible values:

    0 = pending
    1 = active
    2 = deactivated
    3 = application

  • username string

    The name of the user account.

  • countOnly boolean

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

    Default value:

    false

  • limit integer

    A limit on the number of objects to be returned.

    Default value:

    1000

  • page integer

    Page numbering is zero-based and uses the value of the "limit" argument. (For example, if limit=20, then page=0 will display the hits from 1 to 20.)

  • orderBy string, array

    Order the response by the selected field. Multiple values can be passed, separated by a comma.

Request with curl
-d 'curl -L -X GET 'https://[subdomain.itempath.com or IP]/api/users' \
-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 /api/users
post

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).

  • email string
    REQUIRED

    The email address associated with the user.

  • roleId integer
    REQUIRED

    The ID assigned to the user group.

  • roleName string

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

  • language string

    User's language settings.

    Possible values:

    en
    fr

    Default value:

    en

  • type string

    Whether the user is a regular user or can generate application tokens.

    Possible values:

    user
    application

    Default value:

    user

  • timeZone string

    The time zone chosen in the user's settings. Time zone will be the global default if none is set.

Request with curl
curl "http://[subdomain.itempath.com or IP]/api/users" \ -X post \ -H "Content-Type: application/json" \ -H "Authorization: Bearer [Your JWT Access Token]" \
-d '{
	"username": "example",
	"email": "test@example.com",
	"password": "example",
	"roleId": 2
}'
Example Response
{
    "user": {
        "email": "test@example.com",
        "id": 2,
        "isAdmin": null,
        "language": "en",
        "permissions": {},
        "roleId": 2,
        "roleName": Supervisors,
        "status": 0,
        "timeZone": null,
        "type": "user",
        "username": "example",
        "viewId": null
    }
}
Show User /api/users/[ID]
get

Get an ItemPath user by ID.

Request with curl
curl "http://[subdomain.itempath.com or IP]/api/users/[ID]" \ -X get \ -H "Content-Type: application/json" \ -H "Authorization: Bearer [Your JWT Access Token]"
Example Response
{
    "user": {
        "email": "test@itempath.com",
        "id": 13,
        "isAdmin": false,
        "language": "en",
        "permissions": {
            "ALLP": {
                "ALL": true
            },
            "CONN": {},
            "DASH": {},
            "EXPL": {
                "VIEW": true
            },
            "EXPO": {},
            "FILE": {},
            "LOGS": {},
            "PPGS": {},
            "REPO": {
                "CREATE": true,
                "VIEW": true
            },
            "ROLE": {},
            "SETT": {},
            "USER": {},
            "VIEW": {},
            "WORK": {}
        },
        "roleId": 2,
        "roleName": "Supervisors",
        "status": 1,
        "timeZone": "America/Toronto",
        "type": "application",
        "username": "Test User",
        "viewId": 7
    }
}
Update User /users/[ID]
put

Body Parameters

  • email string

    The email address associated with the user.

  • isAdmin boolean

    Whether the user is an administrator or not.

  • language string

    User's language settings.

    Possible values:

    en
    fr

    Default value:

    en

  • password string

    Plaintext password (will be encoded in transit).

  • roleName string

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

  • roleId integer

    The ID assigned to the user group.

  • timeZone string

    The time zone chosen in the user's settings. Time zone will be the global default if none is set.

  • type string

    Whether the user is a regular user or can generate application tokens.

    Possible values:

    user
    application

    Default value:

    user

  • username string

    The name of the user account.

Request with curl
curl "http://[subdomain.itempath.com or IP]/users/[ID]" \ -X put \ -H "Content-Type: application/json" \ -H "Authorization: Bearer [Your JWT Access Token]"
-d '{"type": "application"}'
Example Response
{
    "user": {
        "email": "example@email.com",
        "id": 1,
        "isAdmin": true,
        "language": "en",
        "permissions": {
            "ALLP": {
                "ALL": true
            },
            "CONN": {},
            "DASH": {},
            "EXPL": {},
            "EXPO": {},
            "FILE": {},
            "LOGS": {},
            "PPGS": {},
            "REPO": {},
            "ROLE": {},
            "SETT": {},
            "USER": {},
            "VIEW": {},
            "WORK": {}
        },
        "roleId": 1,
        "roleName": "Example User Group",
        "status": 1,
        "timeZone": "",
        "type": "application",
        "username": "Example User",
        "viewId": 1
    }
}
Delete User /api/users/[ID]/delete
delete

Remove an ItemPath user by ID.

Request with curl
curl "http://[subdomain.itempath.com or IP]/api/users/[ID]/delete" \ -X delete \ -H "Content-Type: application/json" \ -H "Authorization: Bearer [Your JWT Access Token]"
Example Response
{"deleted": "true"}
Generate Application Token /api/users/application-token
post

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://[subdomain.itempath.com or IP]/api/users/application-token" \ -X post \ -H "Content-Type: application/json" \ -H "Authorization: Bearer [Your JWT Access Token]" \ -d '{ }'
Example Response
{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTY1MzA1NjMwNywianRpIjoi"
}