Sign in

v4

latestOpenAPI 3.1.02026-08-02261331761.5 KB
Roles

Create Role

Creates a new tenant role.

post/v2/schema/{proj_id}/{env_id}/roles

Path parameters

proj_idstring required

Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").

Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").

env_idstring required

Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").

Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").

Request body

keystring required

A URL-friendly name of the role (i.e: slug). You will be able to query later using this key instead of the id (UUID) of the role.

namestring required

The name of the role

descriptionstring

optional description string explaining what this role represents, or what permissions are granted to it.

permissionsstring[]

list of action keys that define what actions this resource role is permitted to do

attributesobject

optional dictionary of key-value pairs that can be used to store arbitrary metadata about this role. This metadata can be used to filter role using query parameters with attr_ prefix, currently supports only 'equals' operator

extendsstring[]

list of role keys that define what roles this role extends. In other words: this role will automatically inherit all the permissions of the given roles in this list.

v1compat_settingsobject
v1compat_attributesobject
v1compat_is_built_inboolean

Example request

{
  "key": "editor",
  "name": "Editor",
  "description": "the editor role can read and write to documents",
  "permissions": [
    "document:write"
  ],
  "extends": [
    "viewer"
  ]
}

Response

Successful Response

namestring required

The name of the role

descriptionstring

optional description string explaining what this role represents, or what permissions are granted to it.

permissionsstring[]

list of action keys that define what actions this resource role is permitted to do

attributesobject

optional dictionary of key-value pairs that can be used to store arbitrary metadata about this role. This metadata can be used to filter role using query parameters with attr_ prefix, currently supports only 'equals' operator

extendsstring[]

list of role keys that define what roles this role extends. In other words: this role will automatically inherit all the permissions of the given roles in this list.

v1compat_settingsobject
v1compat_attributesobject
keystring required

A URL-friendly name of the role (i.e: slug). You will be able to query later using this key instead of the id (UUID) of the role.

idstring uuid required

Unique id of the role

organization_idstring uuid required

Unique id of the organization that the role belongs to.

project_idstring uuid required

Unique id of the project that the role belongs to.

environment_idstring uuid required

Unique id of the environment that the role belongs to.

created_atstring date-time required

Date and time when the role was created (ISO_8601 format).

updated_atstring date-time required

Date and time when the role was last updated/modified (ISO_8601 format).

Example response

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "key": "editor",
  "name": "Editor",
  "description": "the editor role can read and write to documents",
  "permissions": [
    "document:write"
  ],
  "extends": [
    "viewer"
  ],
  "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}