Sign in

v4

latestOpenAPI 3.1.02026-08-02261331761.5 KB
Resource Roles

Create Resource Role

Creates a new role associated with the resource.

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

Path parameters

resource_idstring required

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

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

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

Example request

{
  "key": "maintainer",
  "name": "Maintainer",
  "description": "the maintainer role can read from the repo and push changes",
  "permissions": [
    "push"
  ],
  "extends": [
    "contributor"
  ],
  "granted_to": {
    "users_with_role": [
      {
        "role": "Admin",
        "on_resource": "organization",
        "linked_by_relation": "owner"
      }
    ]
  }
}

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.

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.

resource_idstring uuid required

Unique id of the resource that the role belongs to.

resourcestring required

The unique resource key 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": "maintainer",
  "name": "Maintainer",
  "description": "the maintainer role can read from the repo and push changes",
  "permissions": [
    "push"
  ],
  "extends": [
    "contributor"
  ],
  "resource": "repo",
  "granted_to": {
    "id": "8c0a5d99-de8d-4102-b363-7d17843156b3",
    "users_with_role": [
      {
        "role": "Admin",
        "on_resource": "organization",
        "linked_by_relation": "owner",
        "role_id": "4f9ad7ab-15bc-4e25-a5a5-57417b341719",
        "resource_id": "17dbf1da-4061-44a6-8f58-55719560f143",
        "relation_id": "534b2d8a-e8be-4039-828f-0607691ca48c"
      }
    ]
  },
  "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4",
  "resource_id": "40ef0e48-a11f-4963-a229-e396c9f7e7dd",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}