Roles
Roles are the primary authorization structure for Users within the platform.
The roles Object
| Field Name | Type | Description |
|---|---|---|
id | uuid | Primary key of the role (UUID format). |
name | string | Name of the role. |
icon | string | Icon for the role. Displayed in the TrackVision UI. |
description | string | Description for the role. Displayed in the TrackVision UI. |
users | array of objects | The users in this role. One-to-many relationship to users. |
policies | array of objects | The policies assigned to this role. Many-to-many relationship to policies. |
parent | object | The parent role for this role. Many-to-one relationship to roles (recursive). |
children | array of objects | The child roles under this role. One-to-many relationship to roles (recursive). |
List Roles
List all roles that exist in TrackVision.
Request
- REST
- GraphQL
GET /roles
POST /graphql/system
type Query {
roles: [trackvision_roles]
}
Query Parameters
Supports all global query parameters.
Response
An array of up to limit role objects. If no items are available, data will be an empty array.
Example
- REST
- GraphQL
GET /roles
SEARCH /roles
POST /graphql/system
query {
roles {
id
name
users {
email
}
}
}
Retrieve a Role
List an existing role by primary key.
- REST
- GraphQL
GET /roles/:id
POST /graphql/system
type Query {
roles_by_id(id: ID!): trackvision_roles
}
Query Parameters
Supports all global query parameters.
Response
Returns the requested role object.
Example
- REST
- GraphQL
GET /roles/b4cb3b64-8580-4ad9-a099-eade6da24302
POST /graphql/system
query {
roles_by_id(id: 2) {
id
name
users {
email
}
}
}
Create a Role
Create a new role.
Request
- REST
- GraphQL
POST /roles
Provide a role object as the body of your request.
POST /graphql/system
type Mutation {
create_roles_item(data: create_trackvision_roles_input!): trackvision_roles
}
Query Parameters
Supports all global query parameters.
Request Body
A partial role object.
Response
Returns the role object for the created role.
Example
- REST
- GraphQL
POST /roles
{
"name": "Interns",
"icon": "verified_user",
"description": null
}
POST /graphql/system
mutation {
create_roles_item(
data: { name: "Interns", icon: "verified_user", description: null }
) {
id
name
users {
email
}
}
}
Create Multiple Roles
Create multiple new roles.
Request
- REST
- GraphQL
POST /roles
Provide an array of role objects as the body of your request.
POST /graphql/system
type Mutation {
create_roles_items(data: [create_trackvision_roles_input!]!): [trackvision_roles]
}
Query Parameters
Supports all global query parameters.
Request Body
An array of partial role objects.
Response
Returns the role objects for the created roles.
Example
- REST
- GraphQL
POST /roles
[
{
"name": "Interns",
"icon": "verified_user",
"description": null
},
{
"name": "Customers",
"icon": "person",
"description": null
}
]
POST /graphql/system
mutation {
create_roles_items(
data: [
{ name: "Interns", icon: "verified_user", description: null }
{ name: "Customers", icon: "person", description: null }
]
) {
id
name
users {
email
}
}
}
Update a Role
Update an existing role.
Request
- REST
- GraphQL
PATCH /roles/:id
Provide a partial role object as the body of your request.
POST /graphql/system
type Mutation {
update_roles_item(id: ID!, data: update_trackvision_roles_input): trackvision_roles
}
Query Parameters
Supports all global query parameters.
Request Body
A partial role object.
Response
Returns the role object for the updated role.
Example
- REST
- GraphQL
PATCH /roles/c86c2761-65d3-43c3-897f-6f74ad6a5bd7
{
"icon": "attractions"
}
POST /graphql/system
mutation {
update_roles_item(id: "c86c2761-65d3-43c3-897f-6f74ad6a5bd7", data: { icon: "attractions" }) {
id
name
users {
email
}
}
}
Update Multiple Roles
Update multiple existing roles.
Request
- REST
- GraphQL
PATCH /roles
{
"keys": role_id_array,
"data": partial_role_object
}
POST /graphql/system
type Mutation {
update_roles_items(ids: [ID!]!, data: update_trackvision_roles_input): [trackvision_roles]
}
Query Parameters
Supports all global query parameters.
Request Body
keys Required
Array of primary keys of the roles you'd like to update.
data Required
Any of the role object's properties.
Response
Returns the role objects for the updated roles.
Example
- REST
- GraphQL
PATCH /roles
{
"keys": ["c86c2761-65d3-43c3-897f-6f74ad6a5bd7", "6fc3d5d3-a37b-4da8-a2f4-ed62ad5abe03"],
"data": {
"icon": "attractions"
}
}
POST /graphql/system
mutation {
update_roles_items(
ids: ["c86c2761-65d3-43c3-897f-6f74ad6a5bd7", "6fc3d5d3-a37b-4da8-a2f4-ed62ad5abe03"]
data: { icon: "attractions" }
) {
id
name
users {
email
}
}
}
Delete a Role
Delete an existing role.
Request
- REST
- GraphQL
DELETE /roles/:id
POST /graphql/system
type Mutation {
delete_roles_item(id: ID!): delete_one
}
Response
Empty body.
Example
- REST
- GraphQL
DELETE /roles/c86c2761-65d3-43c3-897f-6f74ad6a5bd7
POST /graphql/system
mutation {
delete_roles_item(id: "c86c2761-65d3-43c3-897f-6f74ad6a5bd7") {
id
}
}
Delete Multiple Roles
Delete multiple existing roles.
Request
- REST
- GraphQL
DELETE /roles
Provide an array of role IDs as the body of your request.
POST /graphql/system
type Mutation {
delete_roles_items(ids: [ID!]!): delete_many
}
Request Body
An array of role primary keys
Response
Empty body.
Example
- REST
- GraphQL
DELETE /roles
["653925a9-970e-487a-bfc0-ab6c96affcdc", "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"]
POST /graphql/system
mutation {
delete_roles_items(ids: ["653925a9-970e-487a-bfc0-ab6c96affcdc", "c86c2761-65d3-43c3-897f-6f74ad6a5bd7"]) {
ids
}
}