Permissions

Permissions are assigned to Policies, and control data access throughout the platform.

The permissions Object

Field Name	Type	Description
id	integer	Primary key of the permission rule.
policy	object	Policy this permission applies to. Many-to-one relationship to policies.
collection	string	Collection this permission rule applies to.
action	string	CRUD operation this permission rule applies to. One of create, read, update, delete.
permissions	object	Custom permission rules the item must pass before users with the policy can operate on it. Follows the Filter Rules spec.
validation	object	Rules the provided values must pass before users with the policy can submit them for insertion/update. Follows the Filter Rules spec.
presets	object	Additional default values for the item that are applied by users with the policy.
fields	object	Array of fields the user is allowed to alter.

List Permissions

List all permissions that exist in TrackVision.

Request

REST

GET /permissions

SEARCH /permissions

If using SEARCH you can provide a query object as the body of your request.

Learn more about SEARCH ->

GraphQL

POST /graphql/system

type Query {
	permissions: trackvision_permissions
}

Query Parameters

Supports all global query parameters.

Response

An array of up to limit permission objects. If no items are available, data will be an empty array.

Example

REST

GET /permissions

SEARCH /permissions

GraphQL

POST /graphql/system

query {
	permissions {
		action
		policy
		collection
	}
}

Retrieve a Permission

List an existing permission by primary key.

Request

REST

GET /permissions/:id

GraphQL

POST /graphql/system

type Query {
	permissions_by_id(id: ID!): trackvision_permissions
}

Query Parameters

Supports all global query parameters.

Response

Returns the requested permission object.

Example

REST

GET /permissions/34

GraphQL

POST /graphql/system

query {
	permissions_by_id(id: 34) {
		policy
		collection
		action
	}
}

Create a Permission Rule

Create a new permission rule

Request

REST

POST /permissions

Provide a permission object as the body of your request.

GraphQL

POST /graphql/system

type Mutation {
	create_permissions_item(data: create_trackvision_permissions_input!): trackvision_permissions
}

Query Parameters

Supports all global query parameters.

Request Body

A partial permissions object. action and collection are required.

Response

Returns the permission object for the created permission.

Example

REST

POST /permissions

{
	"collection": "pages",
	"action": "read",
	"policy": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7",
	"fields": ["id", "title"]
}

GraphQL

POST /graphql/system

mutation {
	create_permissions_item(
		data: { collection: "pages", action: "read", policy: "c86c2761-65d3-43c3-897f-6f74ad6a5bd7", fields: ["id", "title"] }
	) {
		id
		collection
		action
	}
}

Create Multiple Permission Rules

Create multiple new permission rules

Request

REST

POST /permissions

Provide an array of permission objects as the body of your request.

GraphQL

POST /graphql/system

type Mutation {
	create_permissions_items(data: [create_trackvision_permissions_input!]!): [trackvision_permissions]
}

Query Parameters

Supports all global query parameters.

Request Body

An array of partial permissions objects. action and collection are required.

Response

Returns the permission objects for the created permissions.

Example

REST

POST /permissions

[
	{
		"collection": "pages",
		"action": "read",
		"policy": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7",
		"fields": ["id", "title"]
	},
	{
		"collection": "pages",
		"action": "create",
		"policy": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7",
		"fields": ["id", "title"]
	}
]

GraphQL

POST /graphql/system

mutation {
	create_permissions_items(
		data: [
			{ collection: "pages", action: "read", policy: "c86c2761-65d3-43c3-897f-6f74ad6a5bd7", fields: ["id", "title"] }
			{ collection: "pages", action: "create", policy: "c86c2761-65d3-43c3-897f-6f74ad6a5bd7", fields: ["id", "title"] }
		]
	) {
		id
		collection
		action
	}
}

Update Permissions

Update an existing permissions rule.

Request

REST

PATCH /permissions/:id

Provide a partial permissions object as the body of your request.

GraphQL

POST /graphql/system

type Mutation {
	update_permissions_item(id: ID!, data: update_trackvision_permissions_input!): trackvision_permissions
}

Query Parameters

Supports all global query parameters.

Request Body

A partial permissions object.

Response

Returns the permission object for the updated permission.

Example

REST

PATCH /permissions/34

{
	"fields": ["id", "title", "body"]
}

GraphQL

mutation {
	update_permissions_item(id: 34, data: { fields: ["id", "title", "body"] }) {
		id
		action
		collection
	}
}

Update Multiple Permissions

Update multiple existing permissions rules.

Request

REST

PATCH /permissions

{
	"keys": permission_id_array,
	"data": partial_permission_object
}

GraphQL

POST /graphql/system

type Mutation {
	update_permissions_items(id: [ID!]!, data: update_trackvision_permissions_input!): [trackvision_permissions]
}

Query Parameters

Supports all global query parameters.

Request Body

keys Required
Array of primary keys of the permissions you'd like to update.

data Required
Any of the permission object's properties.

Returns

Returns the permission object for the updated permissions.

Example

REST

PATCH /permissions

{
	"keys": [34, 65],
	"data": {
		"fields": ["id", "title", "body"]
	}
}

GraphQL

mutation {
	update_permissions_items(ids: [34, 64], data: { fields: ["id", "title", "body"] }) {
		id
		action
		collection
	}
}

Delete Permissions

Delete an existing permissions rule

Request

REST

DELETE /permissions/:id

GraphQL

POST /graphql/system

type Mutation {
	delete_permissions_item(id: ID!): delete_one
}

Response

Empty body.

Example

REST

DELETE /permissions/34

GraphQL

POST /graphql/system

mutation {
	delete_permissions_item(id: 34) {
		id
	}
}

Delete Multiple Permissions

Delete multiple existing permissions rules

Request

REST

DELETE /permissions

Provide an array of permissions IDs as the body of your request.

GraphQL

POST /graphql/system

type Mutation {
	delete_permissions_items(ids: [ID!]!): delete_many
}

Request Body

An array of permission primary keys

Response

Empty body.

Example

REST

DELETE /permissions

[34, 64]

GraphQL

mutation {
	delete_permissions_items(ids: [34, 64]) {
		ids
	}
}

Get Current User Permissions

Check the current user's permissions across all collections.

Request

REST

GET /permissions/me

GraphQL

query {
    permissions_me
}

Response

The response is an object that contains one entry for every collection with at least one permission. Each collection has entries corresponding to the actions the user is able to perform on the collection.

The access property indicates the level of access the user has for an action for a collection. "none" means the user has no access, "partial" means the user has access to some items, but may not have access to all items, and "full" means the user has access to all items.

{
  "data": {
    "<collection>": {
      "create": {
        "access": "none" | "partial" | "full",
        "fields": permission_fields,
        "presets": permission_presets
      },
      "read": {
        "access": "none" | "partial" | "full",
        "full_access": boolean,
        "fields": permission_fields,
      },
      "update": {
        "access": "none" | "partial" | "full",
        "full_access": boolean,
        "fields": permission_fields,
        "presets": permission_presets
      },
      "delete": {
        "access": "none" | "partial" | "full",
        "full_access": boolean
      },
      "share": {
        "access": "none" | "partial" | "full",
        "full_access": boolean
      }
    }
  }
}

Example

REST

GET /permissions/me

{
  "data": {
    "articles": {
      "create": {
        "access": "full",
        "fields": [
          "*"
        ],
        "presets": {
          "title": "New Article"
        }
      },
      "read": {
        "access": "partial",
        "fields": [
          "*"
        ]
      },
      "update": {
        "access": "full",
        "fields": [
          "*"
        ],
        "presets": {}
      },
      "delete": {
        "access": "full"
      },
      "share": {
        "access": "none"
      }
    }
  }
}

GraphQL

N/A

Check Permissions for a Specific Item

Check the current user's permissions on a specific item.

Request

REST

GET /permissions/me/:collection/:id?

GraphQL

N/A

Response

{
	"data": {
		"update": {
			"access": boolean
		},
		"delete": {
			"access": boolean
		},
		"share": {
			"access": boolean
		}
	}
}

For a Singleton where update access is given, the presets and fields properties from the corresponding update permission are additionally returned:

{
	"data": {
		"update": {
			"access": true,
			"presets": permission_presets,
			"fields": permission_fields
		},
		"delete": {
			"access": boolean
		},
		"share": {
			"access": boolean
		}
	}
}

Non-existing Collection / Item

The response structure is maintained in any case, even if the collection or item does not exist. To check for the existence of an item, use the filtering endpoint instead.

Example

REST

GET /permissions/me/articles/15

{
	"data": {
		"update": {
			"access": true
		},
		"delete": {
			"access": false
		},
		"share": {
			"access": false
		}
	}
}

GET /permissions/me/about

{
	"data": {
		"update": {
			"access": true,
			"presets": {},
			"fields": ["*"]
		},
		"delete": {
			"access": false
		},
		"share": {
			"access": false
		}
	}
}

GraphQL

N/A