# Roles

Roles are groups of users that share permissions.

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

# 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

← Revisions SCIM →