1. Docs
  2. API Reference
  3. Bootstrap the Environment's permission catalog and roles

Bootstrap the Environment's permission catalog and roles

POST/portal/v1/accounts/{accountSlug}/applications/{appSlug}/environments/{envSlug}/setup/access-bootstrap

One-shot first-run setup for the active Environment: creates resource.action permissions from the supplied resources and creates roles, attaching the named permission keys to each. Guarded to run only on an unconfigured Environment — it returns 409 if any custom permission or non-system role already exists. Existing permissions and roles encountered during the run are skipped rather than failing; returns 201 with counts of permissions and roles created and skipped, and emits an access.bootstrapped 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.

Request body

application/json

resourcesBootstrapResourceDto[] Required

Resources to generate permissions for

rolesBootstrapRoleDto[] Required

Roles to create with their permission assignments

Responses

application/json

  • dataAccessBootstrapResponseDto*

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.

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

AccessBootstrapResponseDtoView all properties on this resource
Request
curl -X POST "https://auth.canopy-io.com/portal/v1/accounts/{accountSlug}/applications/{appSlug}/environments/{envSlug}/setup/access-bootstrap" \
  -H "Authorization: Bearer $CANOPY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resources": [
      {
        "name": "notes",
        "actions": [
          "create",
          "read",
          "update",
          "delete"
        ]
      }
    ],
    "roles": [
      {
        "name": "Admin",
        "description": "Full access to all resources",
        "permission_keys": [
          "notes.create",
          "notes.read",
          "notes.update",
          "notes.delete"
        ]
      }
    ]
  }'
Response
{
  "data": {
    "permissions_created": 0,
    "roles_created": 0,
    "skipped_permissions": 0,
    "skipped_roles": 0
  }
}
 Related endpoints
POSTAdd resource permissions to existing roles
 Was this page helpful?

Tell us how we can improve this guide.

Canopy