Pivot user statuses API

You can use the Pivot user statuses API to create, read, and modify user statuses—for example, to set and remove the disabled status for a user.

Pivot must be running in native users mode.

Get all user statuses

Returns a list of all user statuses.

URL

GET /api/v1/user-statuses

Success response

Code	Description
200	”status": "ok"

Sample request

curl --location --request GET 'http://localhost:9095/api/v1/user-statuses' \
--header 'x-imply-api-token:<token>'

Sample success response

{
    "userStatuses": [
        {
            "name": "admin@company.com"
        },
        {
            "name": "analyst@company.com",
            "disabled": "2022-09-21T19:01:25.872Z"
        }
    ]
}

Get a user status

Returns a user status with a specified name. The name corresponds to the user ID in the Pivot UI.

URL

GET /api/v1/user-statuses/{name}

Success response

Code	Description
200	”status": "ok"

Sample error response

Code	Example body
404 Not Found	”error": "This user status does not exist."

Sample request

curl --location --request GET 'http://localhost:9095/api/v1/user-statuses/analyst@company.com' \
--header 'x-imply-api-token:<token>'

Sample success response

{
    "userStatuses": [
        {
            "name": "analyst@company.com",
            "disabled": "2022-09-21T19:01:25.872Z"
        }
    ]
}

Set a user status

Sets the status of a user with a specified name. The name corresponds to the user ID in the Pivot UI.

URL

POST /api/v1/user-statuses/{name}

If you send a POST request to /api/v1/user-statuses without {name} and include a new name in the request body, Pivot creates a user status entry for that name. There's no validation to check that the name is an existing user ID.

Sample request

curl -X 'POST' \
  'http://localhost:9095/api/v1/user-statuses/admin@company.com' \
  -H 'accept: application/json' \
  -H 'x-imply-api-token: <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "userStatus": {
    "name": "admin@company.com",
    "disabled": "2022-07-21T19:01:25.872Z"
  }
}'

To re-enable a user, omit the "disabled" property from the message body. For example, the following sample request re-enables the admin@company.com user:

curl -X 'POST' \
  'http://localhost:9095/api/v1/user-statuses/admin@company.com' \
  -H 'accept: application/json' \
  -H 'x-imply-api-token: <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "userStatus": {
    "name": "admin@company.com"
  }
}'

Success response

Code	Description
200	”status": "ok"

Sample error response

Code	Example body
404 Not Found	”error": "the name you entered does not match"

Sample success response

{
  "status":"ok",
  "message":"Updated successfully",
  "userStatus":
  {
    "name":"admin@company.com",
    "disabled":"2022-07-21T19:01:25.872Z"
  }
}

Delete a user status

If you use the Pivot users API to delete a user, you should also delete the corresponding user status. The name corresponds to the user ID in the Pivot UI.

Note that if you want to re-enable a disabled user, you should send a POST request to /user-statuses/{name} without the disabled property as shown in Set a user status.

URL

DELETE /api/v1/user-statuses/{name}

Sample request

curl -X DELETE --header "x-imply-api-token:<token>" localhost:9095/api/v1/user-statuses/analyst@company.com

Success response

Code	Description
200	”status": "ok"

Sample error response

Code	Example body
404 Not Found	”error": "This user status does not exist. Please check the name again"

Sample success response

{
    "status": "ok",
    "message": "Deleted successfully"
}