GET/permissions

Returns the complete, static catalogue of permission strings the platform understands. Read it before building a role payload: POST /roles and PATCH /roles/{id} reject any string that is not in permissions.

assignableToCustomRoles is false for the permissions no custom role may ever hold - today workspace:delete and billing:manage. Requesting one of those in a role payload fails with 400 request.body_invalid, so filter on this flag when rendering a permission picker.

byResource is the same catalogue grouped by the part of the string before the colon, convenient for building a grouped UI. systemRoles gives the exact permission list behind owner, admin and viewer, which is what makes it possible to predict what a role change will grant. Beyond the catalogue ceiling, a caller can still only grant permissions they hold themselves.

The payload is static and not paginated; limit and offset are accepted by the middleware but have no effect.

Requires the roles:read scope.

curl --request GET \
  --url 'https://api.envless.cloud/permissions' \
  --header 'Authorization: Bearer ev_sk_xxxxxxxxxxxx'

Try itGEThttps://api.envless.cloud/permissions

Authorization

Authorizationstringrequiredheader
Bearer token: an Envless API key (ev_sk_…), created in the dashboard or with POST /keys. The key is bound to one workspace; every request runs inside it.

Responses

200OK

List the permission catalogue succeeded.

successbooleanrequired
codeintegerrequired
The HTTP status of this response, repeated in the body.
messagestringrequired
errornullrequired
dataobjectrequired
Show child attributesHide child attributes
- permissionsobject[]required
  Every permission the platform recognises.
  Show child attributesHide child attributes
  namestringrequired
  The permission string, e.g. variables:read. Use this verbatim in role payloads.
  resourcestringrequired
  The part before the colon, e.g. variables.
  assignableToCustomRolesbooleanrequired
  False for permissions no custom role may hold (workspace:delete, billing:manage). Only owner holds those.
- byResourceobjectrequired
  The same permissions grouped by resource, keyed by resource name.
  Any key, values: string[]
- systemRolesobjectrequired
  The permission list behind each system role, keyed by system role key.
  Show child attributesHide child attributes
  ownerstring[]
  Every permission in the catalogue.
  adminstring[]
  viewerstring[]
_reqobject
Show child attributesHide child attributes
- reqIdstring
- resTimeinteger | null

{
    "success": true,
    "code": 200,
    "message": "OK",
    "error": null,
    "data": {
        "permissions": [
            {
                "name": "<string>",
                "resource": "<string>",
                "assignableToCustomRoles": true
            }
        ],
        "byResource": {
            "<key>": [
                "<string>"
            ]
        },
        "systemRoles": {
            "owner": [
                "<string>"
            ],
            "admin": [
                "<string>"
            ],
            "viewer": [
                "<string>"
            ]
        }
    },
    "_req": {
        "reqId": "<string>",
        "resTime": 1
    }
}

Error envelope

Every failure below returns the same shape with success: false; branch on error.code, never on message.

successbooleanrequired
codeintegerrequired
The HTTP status of this response, repeated in the body.
messagestringrequired
errorobjectrequired
Machine-readable failure detail. Null on success.
Show child attributesHide child attributes
- codeenum<string>required
  Stable error code. Branch on this, never on message.
  Options: "auth.api_key_required", "auth.api_key_not_found", "auth.api_key_user_missing", "auth.api_key_owner_not_member", "auth.scope_missing", "auth.scope_ceiling_exceeded", "auth.key_project_restricted", "auth.product_restricted", "auth.permission_denied", "auth.self_mutation_forbidden", "auth.step_up_required", "auth.step_up_fresh_required", "auth.cli_token_not_accepted", "auth.two_factor_required", "auth.workspace_two_factor_required", "auth.two_factor_invalid", "auth.two_factor_replayed", "auth.two_factor_locked", "auth.two_factor_not_enabled", "auth.two_factor_already_enabled", "request.body_must_be_json", "request.body_invalid", "request.body_too_large", "request.rate_limited", "request.invalid_pagination", "workspace.not_found", "workspace.slug_conflict", "workspace.limit_reached", "workspace.delete_last", "workspace.delete_too_early", "workspace.delete_has_projects", "domain.not_configured", "domain.not_found", "domain.invalid", "domain.taken", "domain.attempt_limit", "product.not_found", "product.slug_conflict", "product.locked", "project.not_found", "project.ambiguous_product", "project.slug_conflict", "environment.not_found", "environment.slug_conflict", "environment.expose_disabled", "environment.expose_private_product", "variable.not_found", "variable.name_conflict", "variable.ciphertext_invalid", "variable.baseline_drifted", "version.not_found", "member.not_found", "member.already_exists", "member.self_invite", "member.self_mutation", "member.owner_immutable", "member.owner_cannot_leave", "member.seat_limit", "invite.already_pending", "role.owner_not_assignable", "role.limit_reached", "role.immutable", "role.in_use", "invite.not_found", "invite.expired", "role.not_found", "role.name_conflict", "key.not_found", "key.limit_reached", "webhook.not_found", "webhook.delivery_not_found", "plan.limit_reached", "plan.upgrade_required", "request.not_found", "request.method_not_allowed", "request.conflict", "auth.unauthorized", "auth.forbidden", "request.invalid", "server.error"
- resourcestring
  The resource or scope the failure relates to.
- fieldstring
  The request field that caused the failure.
dataobject | nullrequired
Null on most failures. A plan limit carries { limit, current }.
_reqobject
Show child attributesHide child attributes
- reqIdstring
- resTimeinteger | null

{
    "success": false,
    "code": 401,
    "message": "Something went wrong.",
    "error": {
        "code": "auth.api_key_required",
        "resource": "<string>",
        "field": "<string>"
    },
    "data": {},
    "_req": {
        "reqId": "<string>",
        "resTime": 1
    }
}

401Unauthorized

auth.api_key_required - the Authorization header is missing, or its value does not start with ev_sk_.
auth.api_key_not_found - the key is unknown, inactive or revoked.
auth.api_key_user_missing - the key is valid but its owner no longer exists.
auth.api_key_owner_not_member - the key's owner is no longer a member of the key's workspace.

403Forbidden

auth.workspace_two_factor_required - the workspace requires two-factor authentication and the key's owner has not turned it on.
auth.scope_missing - the key lacks a scope this operation requires; error.resource names it.

500Internal Server Error

server.error - an unexpected error; retry with backoff.

503Service Unavailable

server.error - the API is in maintenance mode or is missing its configuration; retry with backoff.

Authorization#

Responses#

200OK#

Error envelope#

401Unauthorized#

403Forbidden#

500Internal Server Error#

503Service Unavailable#