Skip to main content

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​

CodeDescription
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​

CodeDescription
200"status": "ok"

Sample error response​

CodeExample 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​

CodeDescription
200"status": "ok"

Sample error response​

CodeExample 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​

CodeDescription
200"status": "ok"

Sample error response​

CodeExample 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​

CodeDescription
200"status": "ok"

Sample error response​

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

Sample response​

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