Roles¶

Built-in and custom roles, and the actions a role may hold.

Paths are relative to your API address. See Authentication and Operations. Changes that answer 202 Accepted return an operation to follow.

Request and response examples are generated from the schema; the tables under Schemas are the reference.

List what a project's roles may hold¶

GET /v1/orgs/{org_id}/projects/{project_id}/role-actions

Every action a project role may hold, in words, and whether you hold it here.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`org_id`	path	string		No
`project_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "items": [
        {
            "action": "string",
            "description": "string",
            "held": true,
            "held_on_every_project": true,
            "scopes": [
                "organization"
            ]
        }
    ]
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

List a project's roles¶

GET /v1/orgs/{org_id}/projects/{project_id}/roles

The built-in project roles, the organization's project roles, and this project's own roles: every role that can be given on this project.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`org_id`	path	string		No
`project_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "items": [
        {
            "actions": [
                "string"
            ],
            "builtin": true,
            "created_at": "2022-04-13T15:42:05.901Z",
            "description": "string",
            "holders": 0,
            "id": "string",
            "keystone_role": "member",
            "name": "string",
            "project_id": "string",
            "scope": "organization",
            "updated_at": "2022-04-13T15:42:05.901Z",
            "version": 0
        }
    ]
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Create a project role¶

POST /v1/orgs/{org_id}/projects/{project_id}/roles

Makes a role for this project only, from actions you hold on it.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`org_id`	path	string		No
`project_id`	path	string		No

Request body

application/json201 Created

{
    "actions": [
        "string"
    ],
    "description": "string",
    "name": "string"
}

Responses

application/jsonapplication/json

{
    "actions": [
        "string"
    ],
    "builtin": true,
    "created_at": "2022-04-13T15:42:05.901Z",
    "description": "string",
    "holders": 0,
    "id": "string",
    "keystone_role": "member",
    "name": "string",
    "project_id": "string",
    "scope": "organization",
    "updated_at": "2022-04-13T15:42:05.901Z",
    "version": 0
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Delete a project's role¶

DELETE /v1/orgs/{org_id}/projects/{project_id}/roles/{project_role_id}

Deletes one of this project's roles nobody holds. Send its version in If-Match.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`if-match`	header	string		Yes
`org_id`	path	string		No
`project_id`	path	string		No
`project_role_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "id": "string",
    "status": "string"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Read a project's role¶

GET /v1/orgs/{org_id}/projects/{project_id}/roles/{project_role_id}

One of this project's own roles.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`org_id`	path	string		No
`project_id`	path	string		No
`project_role_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "actions": [
        "string"
    ],
    "builtin": true,
    "created_at": "2022-04-13T15:42:05.901Z",
    "description": "string",
    "holders": 0,
    "id": "string",
    "keystone_role": "member",
    "name": "string",
    "project_id": "string",
    "scope": "organization",
    "updated_at": "2022-04-13T15:42:05.901Z",
    "version": 0
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Change a project's role¶

PATCH /v1/orgs/{org_id}/projects/{project_id}/roles/{project_role_id}

Renames one of this project's roles or changes its actions, for everyone who holds it. Send its current version in If-Match.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`if-match`	header	string		Yes
`org_id`	path	string		No
`project_id`	path	string		No
`project_role_id`	path	string		No

Request body

application/json200 OK

{
    "actions": [
        "string"
    ],
    "description": "string",
    "name": "string"
}

Responses

application/jsonapplication/jsonapplication/json

{
    "actions": [
        "string"
    ],
    "builtin": true,
    "created_at": "2022-04-13T15:42:05.901Z",
    "description": "string",
    "holders": 0,
    "id": "string",
    "keystone_role": "member",
    "name": "string",
    "project_id": "string",
    "scope": "organization",
    "updated_at": "2022-04-13T15:42:05.901Z",
    "version": 0
}

202 Accepted

{
    "operation": {
        "href": "string",
        "id": "string",
        "state": "string"
    }
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

List what custom roles may hold¶

GET /v1/orgs/{org_id}/role-actions

Every action a custom organization or project role may hold, in words, and whether you hold it: you can only put actions you hold into a role.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`org_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "items": [
        {
            "action": "string",
            "description": "string",
            "held": true,
            "held_on_every_project": true,
            "scopes": [
                "organization"
            ]
        }
    ]
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

List roles¶

GET /v1/orgs/{org_id}/roles

The built-in organization and project roles, then the organization's custom roles: organization roles, and project roles usable on every project. A project's own roles are under the project.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`org_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "items": [
        {
            "actions": [
                "string"
            ],
            "builtin": true,
            "created_at": "2022-04-13T15:42:05.901Z",
            "description": "string",
            "holders": 0,
            "id": "string",
            "keystone_role": "member",
            "name": "string",
            "project_id": "string",
            "scope": "organization",
            "updated_at": "2022-04-13T15:42:05.901Z",
            "version": 0
        }
    ]
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Create a custom role¶

POST /v1/orgs/{org_id}/roles

Makes a role from actions you hold yourself. An organization role is given to members; a project role is given on any of the organization's projects.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`org_id`	path	string		No

Request body

application/json201 Created

{
    "actions": [
        "string"
    ],
    "description": "string",
    "name": "string",
    "scope": "organization"
}

Responses

application/jsonapplication/json

{
    "actions": [
        "string"
    ],
    "builtin": true,
    "created_at": "2022-04-13T15:42:05.901Z",
    "description": "string",
    "holders": 0,
    "id": "string",
    "keystone_role": "member",
    "name": "string",
    "project_id": "string",
    "scope": "organization",
    "updated_at": "2022-04-13T15:42:05.901Z",
    "version": 0
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Delete a custom role¶

DELETE /v1/orgs/{org_id}/roles/{role_id}

Deletes a custom role nobody holds: give its holders another role first. Send its current version in If-Match.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`if-match`	header	string		Yes
`org_id`	path	string		No
`role_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "id": "string",
    "status": "string"
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Read a role¶

GET /v1/orgs/{org_id}/roles/{role_id}

A built-in role by its name, or one of the organization's own by its ID.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`org_id`	path	string		No
`role_id`	path	string		No

Responses

200 OK

application/jsonapplication/json

{
    "actions": [
        "string"
    ],
    "builtin": true,
    "created_at": "2022-04-13T15:42:05.901Z",
    "description": "string",
    "holders": 0,
    "id": "string",
    "keystone_role": "member",
    "name": "string",
    "project_id": "string",
    "scope": "organization",
    "updated_at": "2022-04-13T15:42:05.901Z",
    "version": 0
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Change a custom role¶

PATCH /v1/orgs/{org_id}/roles/{role_id}

Renames a custom role or changes its actions, for everyone who holds it, from their next request. Send its current version in If-Match. Taking away the last action that wrote workloads also takes member away in each location: that is 202 with the operation.

Input parameters

Parameter	In	Type	Default	Nullable	Description
`Authorization`	header	string	N/A	No	Bearer followed by a service account's API key. The console uses your signed-in session instead.
`idempotency-key`	header	string		Yes
`if-match`	header	string		Yes
`org_id`	path	string		No
`role_id`	path	string		No

Request body

application/json200 OK

{
    "actions": [
        "string"
    ],
    "description": "string",
    "name": "string"
}

Responses

application/jsonapplication/jsonapplication/json

{
    "actions": [
        "string"
    ],
    "builtin": true,
    "created_at": "2022-04-13T15:42:05.901Z",
    "description": "string",
    "holders": 0,
    "id": "string",
    "keystone_role": "member",
    "name": "string",
    "project_id": "string",
    "scope": "organization",
    "updated_at": "2022-04-13T15:42:05.901Z",
    "version": 0
}

202 Accepted

{
    "operation": {
        "href": "string",
        "id": "string",
        "state": "string"
    }
}

422 Unprocessable Entity

{
    "detail": [
        {
            "ctx": {},
            "input": null,
            "loc": [
                null
            ],
            "msg": "string",
            "type": "string"
        }
    ]
}

Schemas¶

Accepted¶

Name	Type	Description
`operation`	OperationLink

HTTPValidationError¶

Name	Type	Description
`detail`	Array<ValidationError>

OperationLink¶

Name	Type	Description
`href`	string	Where to read the operation; also the `Location` header.
`id`	string	The operation's ID (`op_…`).
`state`	string \| null	Its state when accepted, normally `queued`.

ProjectRoleBody¶

Name	Type	Description
`actions`	Array<string>
`description`	string
`name`	string

Role¶

Name	Type	Description
`actions`	Array<string>	What it allows (`GET …/role-actions` says each).
`builtin`	boolean	Built-in roles cannot be changed or deleted.
`created_at`	string(date-time) \| null
`description`	string
`holders`	integer \| null	Members, project grants and pending invitations that hold it now; null for built-in roles.
`id`	string	`rol_…` for a custom role; the name for a built-in one.
`keystone_role`	string \| null	For a project role: its access in each location's own tools — `member`, `reader` where the location enforces read-only, or none (portal and API only).
`name`	string
`project_id`	string \| null	For a project's own role, that project (`prj_…`); otherwise null.
`scope`	string	`organization`: held as a member's role. `project`: held on a project.
`updated_at`	string(date-time) \| null
`version`	integer \| null	Its version, also its `ETag`; null when built in.

RoleAction¶

Name	Type	Description
`action`	string
`description`	string
`held`	boolean	Whether you hold it where the roles listed here are made, so may put it in a role.
`held_on_every_project`	boolean	Under the organization only: whether you hold it on every project, for project roles made for the whole organization.
`scopes`	Array<string>	The role scopes it may be part of.

RoleActionList¶

Name	Type	Description
`items`	Array<RoleAction>

RoleBody¶

Name	Type	Description
`actions`	Array<string>
`description`	string
`name`	string
`scope`	string

RoleChange¶

Name	Type	Description
`actions`	Array<string>
`description`	string \| null
`name`	string \| null

RoleDeleted¶

Name	Type	Description
`id`	string
`status`	string

RoleList¶

Name	Type	Description
`items`	Array<Role>

ValidationError¶

Name	Type	Description
`ctx`
`input`
`loc`	Array<>
`msg`	string
`type`	string