Create a custom role

POST

/portal/v1/accounts/{accountSlug}/applications/{appSlug}/environments/{envSlug}/roles

Creates a custom role in the active Application for the current Environment from a name and optional description. Without organization_id it is an Environment role, assignable in every organization; with it, the role belongs to that organization and can be held only at its node or beneath it (400 rbac.role_outside_organization elsewhere). The new role is always non-system and starts with no permissions, or with a copy of copy_from_role_id's (an Environment role, or one of the same organization) — otherwise attach permission keys via the role-permissions endpoint. A name already used in the same tier (the Environment's roles, or that organization's own) returns 409. Requires the rbac.manage_roles permission and emits a role.created audit event.

Authentication

Bearer TokenAuthorization

JWT access token. Never send alongside X-API-Key: a request carrying both is refused.

Requires capability env_roles.manageDeveloper Console

Create, edit, and delete roles and set their permissions. Granted through an administrator role in the Admin Workspace; a valid token without it is refused with 403.

Path Parameters

accountSlugstring Required

The Account's slug. An unknown one answers 404.

appSlugstring Required

The Application's slug within the Account.

envSlugstring Required

The Environment's slug within the Application.

Request body

application/json

namestring Required

Role name, unique among the Environment's roles, or among the organization's own when `organization_id` is set

descriptionstring Optional

Role description

organization_idstring Optional

The organization the role belongs to. Omitted, the role is an Environment role, assignable in every organization; set, it can be held only at the organization's node or beneath it.

copy_from_role_idstring Optional

Start from a copy of this role's permissions (and its description, when none is given). An Environment role, or a role of the same organization. The only way an organization gets its own version of a shared role.

Responses

application/json

dataRoleResponseDto*

application/json

errorApiErrorBodyDto*

application/json

errorApiErrorBodyDto*

application/json

errorApiErrorBodyDto*

application/json

errorApiErrorBodyDto*

application/json

errorApiErrorBodyDto*

Errors

When the request can't be completed, the response body includes a stable error code you can branch on, and a correlation_id (also sent as the X-Correlation-Id header). Quote the correlation id when you contact support: it identifies the exact request in Canopy's logs.

403account.capability_requiredForbidden

When it happens

The signed-in user's administrator roles do not grant the capability this endpoint requires.

Remediation

Ask an account administrator to grant a role carrying the capability named in the Authentication section, then retry.

Returned object

RoleResponseDtoView all properties on this resource

Request

curl -X POST "https://auth.canopy-io.com/portal/v1/accounts/value/applications/value/environments/value/roles" \
  -H "Authorization: Bearer $CANOPY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "description": "string",
    "organization_id": "string",
    "copy_from_role_id": "string"
  }'

Response

{
  "data": {
    "id": "string",
    "name": "string",
    "scope": "environment",
    "organization_node_id": "string",
    "organization_name": "string",
    "description": "string",
    "is_system_role": false,
    "system_key": "string",
    "is_active": false,
    "created_at": "2026-04-20T12:00:00.000Z",
    "updated_at": "2026-04-20T12:00:00.000Z",
    "version": 0,
    "permission_count": 0,
    "member_count": 0,
    "administers": false
  }
}

GETList roles
GETGet a role
PATCHUpdate a role
DELETEDelete a role
GETGet permissions for a role
PUTReplace permissions on a role

Was this page helpful?

Tell us how we can improve this guide.