Pivot roles API

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

Pivot must be running in native users mode.

Get all roles

Returns a list of all roles.

URL

GET /api/v1/roles

Success response

Code	Description
200	"status": "ok"

Sample request

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

Sample response

{
    "roles": [
        {
            "name": "super-admin",
            "title": "Super Admin",
            "permissions": [
                {
                    "name": "ManageUsers"
                },
                {
                    "name": "ManageUserRoles"
                }
            ]
        },
        {
            "name": "fc50",
            "title": "Analysts France",
            "permissions": [
                {
                    "name": "AccessVisualization"
                }
            ],
            "filterTokens": [
                {
                    "name": "france-filter-token",
                    "formula": "t.channel IN ('#fr.wikipedia', '#en.wikipedia')"
                }
            ]
        }
    ]
}

Get a role

Returns a role with a specified name.

URL

GET /api/v1/roles/{name}

Success response

Code	Description
200	"status": "ok"

Sample error response

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

Sample request

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

Sample response

{
    "role": {
        "name": "fc50",
        "title": "Analysts France",
        "permissions": [
            {
                "name": "AccessVisualization"
            }
        ],
        "filterTokens": [
            {
                "name": "france-filter-token",
                "formula": "t.channel IN ('#fr.wikipedia', '#en.wikipedia')"
            }
        ]
    }
}

Create a role

Creates a role with a specified name.

URL

POST /api/v1/roles

Sample request

curl -X POST 'http://PIVOT_URL/api/v1/roles' \
--header 'x-imply-api-token: <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "role": {
        "name": "fc50",
        "title": "Analysts France",
        "externalName": "analyst-user",
        "roleVisibility": "public",
        "memberVisibility": "hidden",
        "permissions": [
            {
                "name": "AccessVisualization"
            }
        ],
        "filterTokens": [
            {
                "name": "france-filter-token",
                "formula": "t.channel IN ('\''#fr.wikipedia'\'', '\''#en.wikipedia'\'')"
            }
        ]
    }
}'

Success response

Code	Description
200	"status": "ok"

Sample error response

Code	Example body
400 Bad Request	"error": "this name has been used."

Sample response

{
    "status": "ok",
    "message": "Created successfully",
    "role": {
        "name": "fc50",
        "title": "Analysts France",
        "externalName": "analyst-user",
        "roleVisibility": "public",
        "memberVisibility": "hidden",
        "permissions": [
            {
                "name": "AccessVisualization"
            }
        ],
        "filterTokens": [
            {
                "name": "france-filter-token",
                "formula": "t.channel IN ('#fr.wikipedia', '#en.wikipedia')"
            }
        ]
    }
}

Update a role

Updates the details of a role with a specified name.

URL

POST /api/v1/roles/{name}

Sample request

The following example request updates the properties of the fc50 role object to change memberVisibility to public, add ManageConnections to permissions, and updated filterTokens to include the #es.wikipedia channel. The name in the request body must match the {name} in the URL. You can't update the name field.

You must provide all role properties you want to retain in the role, even if you don't want to update them. Pivot recreates the role with the details you specify in the request.

curl -X POST 'http://PIVOT_URL/api/v1/roles/fc50' \
--header 'x-imply-api-token: <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "role": {
        "name": "fc50",
        "title": "Analysts France",
        "externalName": "analyst-user",
        "roleVisibility": "public",
        "memberVisibility": "public",
        "permissions": [
            {
                "name": "AccessVisualization"
            },
            {
                "name": "ManageConnections"
            }
        ],
        "filterTokens": [
            {
                "name": "france-filter-token",
                "formula": "t.channel IN ('\''#fr.wikipedia'\'', '\''#en.wikipedia'\'', '\''#es.wikipedia'\'')"
            }
        ]
    }
}'

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",
    "role": {
        "name": "fc50",
        "title": "Analysts France",
        "externalName": "analyst-user",
        "roleVisibility": "public",
        "memberVisibility": "public",
        "permissions": [
            {
                "name": "AccessVisualization"
            },
            {
                "name": "ManageConnections"
            }
        ],
        "filterTokens": [
            {
                "name": "france-filter-token",
                "formula": "t.channel IN ('#fr.wikipedia', '#en.wikipedia', '#es.wikipedia')"
            }
        ]
    }
}

Delete a role

Deletes a role with a specified name.

URL

DELETE /api/v1/roles/{name}

Sample request

curl -X DELETE 'http://PIVOT_URL/api/v1/roles/fc50' \
--header 'x-imply-api-token:<token>'

Success response

Code	Description
200	"status": "ok"

Sample error response

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

Sample response

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