# # Permissions

> Permissions are assigned to Roles, and control data access throughout the platform. Learn more about Permissions.

- The Permission Object
- List Permissions
- Retrieve a Permission
- Create a Permission Rule
- Create Multiple Permission Rules
- Update Permissions
- Update Multiple Permissions
- Delete Permissions
- Delete Multiple Permissions

## # The Permission Object

`id` uuid
Primary key of the permission rule.

`role` many-to-one
Role this permission applies to. Many-to-one to roles. `null` is used for public permissions.

`collection` string
Collection this permission rule applies to.

`action` string
What CRUD operation this permission rule applies to. One of `create`, `read`, `update`, `delete`.

`permissions` object
What rules the item must pass before the role is allowed to alter it. Follows the Filter Rules spec.

`validation` object
What rules the provided values must pass before the role is allowed to submit them for insertion/update. Follows the Filter Rules spec.

`preset` object
Additional default values for the role.

`fields` array
What fields the user is allowed to alter.

    {
    	"id": 34,
    	"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7",
    	"collection": "pages",
    	"action": "create",
    	"permissions": null,
    	"validation": {
    		"title": {
    			"_contains": "Gitaflow"
    		}
    	},
    	"presets": {
    		"published": false
    	},
    	"fields": ["title", "translations"]
    }

## # List Permissions

List all permissions that exist in Gitaflow.

Permissions

The data returned in this endpoint will be filtered based on the user's permissions. For example, permissions for a role other than the current user's role won't be returned.

### # Query Parameters

Supports all global query parameters.

### # Returns

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

### # REST API

    GET /permissions
    SEARCH /permissions

Learn more about SEARCH ->

### # GraphQL

    POST /graphql/system

    type Query {
    	permissions: gitaflow_permissions
    }

##### # Example

    query {
    	permissions {
    		action
    		role
    		collection
    	}
    }

## # Retrieve a Permission

List an existing permission by primary key.

### # Query Parameters

Supports all global query parameters.

### # Returns

Returns the requested permission object.

### # REST API

    GET /permissions/:id

##### # Example

    // GET /permissions/34

    {
    	"data": {
    		"id": 34,
    		"role": "c86c2761-65d3-43c3-897f-6f74ad6a5bd7",
    		"collection": "pages",
    		"action": "create",
    		"permissions": null,
    		"validation": {
    			"title": {
    				"_contains": "Gitaflow"
    			}
    		},
    		"presets": {
    			"published": false
    		},
    		"fields": ["title", "translations"]
    	}
    }

### # GraphQL

    POST /graphql/system

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

##### # Example

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

## # Create a Permission Rule

Create a new permission rule

### # Query Parameters

Supports all global query parameters.

### # Request Body

A partial permissions object. `action` and `collection` are required.

### # Returns

Returns the permission object for the created permission.

### # REST API

    POST /permissions

##### # Example

    // Request

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

### # GraphQL

    POST /graphql/system

    type Mutation {
    	create_permissions_item(data: create_gitaflow_permissions_input!): gitaflow_permissions
    }

##### # Example

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

## # Create Multiple Permission Rules

Create multiple new permission rules

### # Query Parameters

Supports all global query parameters.

### # Request Body

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

### # Returns

Returns the permission objects for the created permissions.

### # REST API

    POST /permissions

##### # Example

    // Request

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

### # GraphQL

    POST /graphql/system

    type Mutation {
    	create_permissions_items(data: [create_gitaflow_permissions_input!]!): [gitaflow_permissions]
    }

##### # Example

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

## # Update Permissions

Update an existing permissions rule.

### # Query Parameters

Supports all global query parameters.

### # Request Body

A partial permissions object.

### # Returns

Returns the permission object for the updated permission.

### # REST API

    PATCH /permissions/:id

##### # Example

    // PATCH /permissions/34

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

### # GraphQL

    POST /graphql/system

    type Mutation {
    	update_permissions_item(id: ID!, data: update_gitaflow_permissions_input!): gitaflow_permissions
    }

##### # Example

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

## # Update Multiple Permissions

Update multiple existing permissions rules.

### # 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.

### # REST API

    PATCH /permissions

##### # Example

    // PATCH /permissions

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

### # GraphQL

    POST /graphql/system

    type Mutation {
    	update_permissions_items(id: [ID!]!, data: update_gitaflow_permissions_input!): [gitaflow_permissions]
    }

##### # Example

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

## # Delete Permissions

Delete an existing permissions rule

### # Returns

Empty body.

### # REST API

    DELETE /permissions/:id

##### # Example

    DELETE /permissions/34

### # GraphQL

    POST /graphql/system

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

##### # Example

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

## # Delete Multiple Permissions

Delete multiple existing permissions rules

### # Request Body

An array of permission primary keys

### # Returns

Empty body.

### # REST API

    DELETE /permissions

##### # Example

    // DELETE /permissions

    [34, 64]

### # GraphQL

    POST /graphql/system

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

##### # Example

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