Resource Central

Users

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

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"
}