Permissions

Permissions control who has access to what and when.

Endpoints
   GET /:project/permissions
   GET /:project/permissions/:id
   GET /:project/permissions/me
   GET /:project/permissions/me/:collection
  POST /:project/permissions
 PATCH /:project/permissions/:id
DELETE /:project/permissions/:id

The Permissions Object

id integer

Unique identifier for the permission.

collection string

What collection this permission applies to.

role integer

Unique identifier of the role this permission applies to.

status string

What status this permission applies to.

create string

If the user can create items. One of none, full.

read string

If the user can read items. One of none, mine, role, full.

update string

If the user can update items. One of none, mine, role, full.

delete string

If the user can update items. One of none, mine, role, full.

comment string

If the user can post comments. One of none, create, update, full.

explain string

If the user is required to leave a comment explaining what was changed. One of none, create, update, always.

read_field_blacklist array

Explicitly denies read access for specific fields.

write_field_blacklist array

Explicitly denies write access for specific fields.

status_blacklist array

Explicitly denies specific statuses to be used.

Permission Object
{
  "id": 1,
  "collection": "customers",
  "role": 3,
  "status": null,
  "create": "full",
  "read": "mine",
  "update": "none",
  "delete": "none",
  "comment": "update",
  "explain": "none",
  "read_field_blacklist": [],
  "write_field_blacklist": [],
  "status_blacklist": []
}

List the Permissions

List all permissions.

Parameters

project required

The project you're targetting.

Query

fields optional

Control what fields are being returned in the object. Learn more

limit optional

A limit on the number of objects that are returned. Default is 200. Learn more

offset optional

How many items to skip when fetching data. Default is 0. Learn more

page optional

Cursor for use in pagination. Often used in combination with limit. Learn more

sort optional

How to sort the returned items. Learn more

single optional

Return the result as if it was a single item. Useful for selecting a single item based on filters and search queries. Will force limit to be 1. Learn more

filter optional

Select items in collection by given conditions. Learn more

q optional

Filter by items that contain the given search query in one of their fields. Learn more

meta optional

What metadata to return in the response. Learn more

Returns

Returns an array of permission objects.

Endpoint
   GET /:project/permissions
Response
{
  "data": [
    {
      "id": 1,
      "collection": "customers",
      "role": 3,
      "status": null,
      "create": "full",
      "read": "mine",
      "update": "none",
      "delete": "none",
      "comment": "update",
      "explain": "none",
      "read_field_blacklist": [],
      "write_field_blacklist": [],
      "status_blacklist": []
    },
    { ... },
    { ... }
  ]
}

Retrieve a Permission

Retrieve a single permissions object by unique identifier.

Paremeters

project required

The project you're targetting.

id required

Unique identifier of the item.

Query

fields optional

Control what fields are being returned in the object. Learn more

meta optional

What metadata to return in the response. Learn more

Returns

Returns the permissions object for the given unique identifier.

Endpoint
   GET /:project/permissions/:id
Response
{
  "data": {
    "id": 1,
    "collection": "customers",
    "role": 3,
    "status": null,
    "create": "full",
    "read": "full",
    "update": "mine",
    "delete": "mine",
    "comment": "none",
    "explain": "none",
    "read_field_blacklist": [],
    "write_field_blacklist": [],
    "status_blacklist": []
  }
}

List the Current User's Permissions

List the permissions that apply to the current user.

TIP

This endpoint won't work for the public role.

Parameters

project required

The project you're targetting.

Query

No query parameters available.

Returns

Returns an array of permission objects.

Endpoint
   GET /:project/permissions/me
Response
{
  "data": [
    {
      "id": 1,
      "collection": "customers",
      "role": 3,
      "status": null,
      "create": "full",
      "read": "mine",
      "update": "none",
      "delete": "none",
      "comment": "update",
      "explain": "none",
      "read_field_blacklist": [],
      "write_field_blacklist": [],
      "status_blacklist": []
    },
    { ... },
    { ... }
  ]
}

List the Current User's Permissions for Given Collection

List the permissions that apply to the current user for the given collection

TIP

This endpoint won't work for the public role.

Parameters

project required

The project you're targetting.

collection required

Collection of which you want to retrieve the permissions.

Query

No query parameters available.

Returns

Returns a permissions object if available.

Endpoint
   GET /:project/permissions/me/:collection
Response
{
  "data": {
    "id": 1,
    "collection": "customers",
    "role": 3,
    "status": null,
    "create": "full",
    "read": "mine",
    "update": "none",
    "delete": "none",
    "comment": "update",
    "explain": "none",
    "read_field_blacklist": [],
    "write_field_blacklist": [],
    "status_blacklist": []
  }
}

Create a Permission

Create a new permission.

Parameters

project required

The project you're targetting.

Attributes

collection Required

What collection this permission applies to.

role Required

Unique identifier of the role this permission applies to.

status optional

What status this permission applies to.

create optional

If the user can create items. One of none, full.

read optional

If the user can read items. One of none, mine, role, full.

update optional

If the user can update items. One of none, mine, role, full.

delete optional

If the user can update items. One of none, mine, role, full.

comment optional

If the user can post comments. One of none, create, update, full.

explain optional

If the user is required to leave a comment explaining what was changed. One of none, create, update, always.

read_field_blacklist optional

Explicitly denies read access for specific fields.

write_field_blacklist optional

Explicitly denies write access for specific fields.

status_blacklist optional

Explicitly denies specific statuses to be used.

Query

meta optional

What metadata to return in the response. Learn more

Returns

Returns the permissions object for the permission that was just created.

Endpoint
  POST /:project/permissions
Request
{
  "collection": "customers",
  "role": 3,
  "read": "mine",
  "read_field_blacklist": ["featured_image"]
}
Response
{
  "data": {
    "id": 28,
    "collection": "customers",
    "role": 3,
    "status": null,
    "create": "none",
    "read": "mine",
    "update": "none",
    "delete": "none",
    "comment": "none",
    "explain": "none",
    "read_field_blacklist": [
      "featured_image"
    ],
    "write_field_blacklist": [],
    "status_blacklist": []
  }
}

Update a Permission

Update an existing permission

Parameters

project required

The project you're targetting.

id required

Unique identifier of the item.

Attributes

collection optional

What collection this permission applies to.

role optional

Unique identifier of the role this permission applies to.

status optional

What status this permission applies to.

create optional

If the user can create items. One of none, full.

read optional

If the user can read items. One of none, mine, role, full.

update optional

If the user can update items. One of none, mine, role, full.

delete optional

If the user can update items. One of none, mine, role, full.

comment optional

If the user can post comments. One of none, create, update, full.

explain optional

If the user is required to leave a comment explaining what was changed. One of none, create, update, always.

read_field_blacklist optional

Explicitly denies read access for specific fields.

write_field_blacklist optional

Explicitly denies write access for specific fields.

status_blacklist optional

Explicitly denies specific statuses to be used.

Query

meta optional

What metadata to return in the response. Learn more

Returns

Returns the permissions object for the permission that was just updated.

Endpoint
 PATCH /:project/permissions/:id
Request
{
  "read": "full"
}
Response
{
  "data": {
    "id": 28,
    "collection": "customers",
    "role": 3,
    "status": null,
    "create": "none",
    "read": "full",
    "update": "none",
    "delete": "none",
    "comment": "none",
    "explain": "none",
    "read_field_blacklist": [
      "featured_image"
    ],
    "write_field_blacklist": [],
    "status_blacklist": []
  }
}

Delete a Permission

Delete an existing permission

Parameters

project required

The project you're targetting.

id required

Unique identifier of the item.

Returns

Returns an empty body with HTTP status 204

Endpoint
DELETE /:project/permissions/:id