Roles

Roles are groups of users that share permissions.

Endpoints
   GET /:project/roles
   GET /:project/roles/:id
  POST /:project/roles
 PATCH /:project/roles/:id
DELETE /:project/roles/:id

The Role Object

Attributes

id integer

Unique identifier for the role.

name string

Name of the role.

description string

Description of the role.

ip_whitelist array of strings

Array of IP addresses that are allowed to connect to the API as a user of this role.

external_id string

ID used with external services in SCIM.

module_listing object

Custom override for the admin app module bar navigation.

collection_listing object

Custom override for the admin app collection navigation.

enforce_2fa boolean

Whether or not this role enforces the use of 2FA.

Role Object
{
  "id": 1,
  "name": "Administrator",
  "description": "Admins have access to all managed data within the system by default",
  "ip_whitelist": [],
  "external_id": null,
  "module_listing": null,
  "collection_listing": null,
  "enforce_2fa": false
}

List the Roles

List the roles.

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 role objects.

Endpoint
   GET /:project/roles
Response
{
  "data": [
    {
      "id": 1,
      "name": "Administrator",
      "description": "Admins have access to all managed data within the system by default",
      "ip_whitelist": [],
      "external_id": null,
      "module_listing": null,
      "collection_listing": null,
      "enforce_2fa": false
    },
    { ... },
    { ... }
  ]
}

Retrieve a Role

Retrieve a single role by unique identifier.

Parameters

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 role object for the given unique identifier.

Endpoint
   GET /:project/roles/:id
Response
{
  "data": {
    "id": 1,
    "name": "Administrator",
    "description": "Admins have access to all managed data within the system by default",
    "ip_whitelist": [],
    "external_id": null,
    "module_listing": null,
    "collection_listing": null,
    "enforce_2fa": false
  }
}

Create a Role

Create a new role.

Parameters

project required

The project you're targetting.

Attributes

name required

Name of the role.

description optional

Description of the role.

ip_whitelist optional of strings

Array of IP addresses that are allowed to connect to the API as a user of this role.

external_id optional

ID used with external services in SCIM.

module_listing optional

Custom override for the admin app module bar navigation.

collection_listing optional

Custom override for the admin app collection navigation.

enforce_2fa optional

Whether or not this role enforces the use of 2FA.

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 role object for the role that was just created.

Endpoint
  POST /:project/roles
Request
{
  "name": "Interns"
}
Response
{
  "data": {
    "id": 3,
    "name": "Interns",
    "description": null,
    "ip_whitelist": [],
    "external_id": "bcb3e393-624b-4248-9b07-5bd47d2c133f",
    "module_listing": null,
    "collection_listing": null,
    "enforce_2fa": false
  }
}

Update a Role

Update an existing role

Parameters

project required

The project you're targetting.

id required

Unique identifier of the item.

Attributes

name optional

Name of the role.

description optional

Description of the role.

ip_whitelist optional of strings

Array of IP addresses that are allowed to connect to the API as a user of this role.

external_id optional

ID used with external services in SCIM.

module_listing optional

Custom override for the admin app module bar navigation.

collection_listing optional

Custom override for the admin app collection navigation.

enforce_2fa optional

Whether or not this role enforces the use of 2FA.

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 role object for the role that was just updated.

Endpoint
 PATCH /:project/roles/:id
Request
{
  "description": "Limited access only."
}
Response
{
  "data": {
    "id": 3,
    "name": "Interns",
    "description": "Limited access only.",
    "ip_whitelist": [],
    "external_id": "bcb3e393-624b-4248-9b07-5bd47d2c133f",
    "module_listing": null,
    "collection_listing": null,
    "enforce_2fa": false
  }
}

Delete a Role

Delete an existing role

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/roles/:id