Pivot users API

You can use the Pivot users API to create, read, and modify users.

Pivot must be running in native users mode.

Get all users

Returns a list of all users.

URL

GET /api/v1/users

Success response

Code	Description
200	"status": "ok"

Sample request

curl -X GET 'http://PIVOT_URL/api/v1/users' \
--header 'x-imply-api-token:<token>'

Sample response

{
    "users": [
        {
            "name": "admin@example.com",
            "roles": [
                "super-admin"
            ]
        },
        {
            "name": "admin@example.com",
            "colorMode": "dark-color-mode",
            "email": "admin@example.com",
            "firstName": "Admin",
            "lastName": "User",
            "roles": [
                "super-admin"
            ]
        }
    ]
}

Get a user

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

URL

GET /api/v1/users/{name}

Success response

Code	Description
200	"status": "ok"

Sample error response

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

Sample request

curl -X GET 'http://PIVOT_URL/api/v1/users/admin@example.com' \
--header 'x-imply-api-token:<token>'

Sample response

{
    "user": {
        "name": "admin@example.com",
        "colorMode": "dark-color-mode",
        "email": "admin@example.com",
        "firstName": "Admin",
        "lastName": "User",
        "roles": [
            "super-admin"
        ]
    }
}

Create a user

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

URL

POST /api/v1/users

Sample request

curl -X POST 'http://PIVOT_URL/api/v1/users' \
--header 'x-imply-api-token: <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user": {
        "name": "admin@example.com",
        "colorMode": "dark-color-mode",
        "email": "admin@example.com",
        "firstName": "Admin",
        "lastName": "User",
        "status": "new",
        "roles": [
            "super-admin"
        ]
    },
    "sendWelcomeEmail": true,
    "clientUrl": "http://PIVOT_URL"
}'

Set sendWelcomeEmail to true to send a welcome email to the new user with a password change prompt. The default template for the welcome email is in the Pivot configuration file:

emailTemplates:
  - name: invite
    subject: Create your pivot account
    html: 'Please use this link to set your password: ${linkProtocol}://${linkHost}${linkPath}'

To specify a custom invitation email template, add an entry to the emailTemplates object in the Pivot configuration file with name: invite.

To override the default URL in the html property, set clientUrl in your POST request to the URL you want to use.

Success response

Code	Description
200	"status": "ok"

Sample error response

Code	Example body
400 Bad Request	"error": "name must be defined"

Sample response

{
    "status": "ok",
    "message": "Created successfully",
    "user": {
        "name": "admin@example.com",
        "colorMode": "dark-color-mode",
        "email": "admin@example.com",
        "firstName": "Admin",
        "lastName": "User",
        "roles": [
            "super-admin"
        ]
    }
}

Update a user

Updates the details of a user with a specified name. The name corresponds to the user ID in the Pivot UI.

URL

POST /api/v1/users/{name}

Sample request

The following example request updates the roles and email for the user with name admin@example.com. The name in the request body must match the {name} in the URL. You can't update the name field.

curl -X POST 'http://PIVOT_URL/api/v1/users/admin@example.com' \
--header 'x-imply-api-token: <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user": {
        "name": "admin@example.com",
        "email": "new-email@example.com",
        "roles": [
            "connection-manager"
        ]
    }
}'

Success response

Code	Description
200	"status": "ok"

Sample error response

Code	Example body
400 Bad Request	"error": "the name you entered does not match"

Sample response

{
    "status": "ok",
    "message": "Updated successfully",
    "user": {
        "name": "admin@example.com",
        "email": "new-email@example.com",
        "roles": [
            "connection-manager"
        ]
    }
}

To update a user's status, send a POST request to the Pivot user statuses API.

Delete a user

Deletes a user with a specified name. If you delete a user, you should also use the User status API to delete the corresponding user status.

URL

DELETE /api/v1/users/{name}

Sample request

curl -X DELETE 'http://PIVOT_URL/api/v1/users/admin@example.com' \
--header 'x-imply-api-token:<token>'

Success response

Code	Description
200	"status": "ok"

Sample error response

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

Sample response

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