Roles

List available roles

Returns the list of available roles in the system for the organization. This includes both organization-level roles (e.g., org_admin, org_member) and zone-level roles (e.g., zone_manager, zone_viewer).

Each role includes:

name: Internal identifier (e.g., org_admin, zone_manager)
label: Human-readable display name (e.g., Organization Administrator)
scope: Whether the role applies at organization or zone level

get/organizations/{organization_id}/roles

Path parameters

organization_idstring required

Organization ID or label identifier

Organization ID or label

Query parameters

scope'organization' | 'zone'

The scope at which a role can be assigned.

organization: Roles that apply at the organization level (e.g., org_admin)
zone: Roles that apply at the zone level (e.g., zone_manager)

Filter roles by scope (organization or zone level)

expand[]string[]

Fields to expand in the response. Supports "permissions" to include the permissions field with the caller's permissions for the resource. For list organization identities only, "total_count" populates pagination.total_count with the number of identities matching the same filters as the list (excluding cursor and limit). Other operations ignore expand values they do not use.

Headers

X-Client-Request-IDstring uuid

Unique request identifier specified by the originating caller and passed along by proxies.

Response

List of available roles

permissionsOrgManagementPermissions

Permissions granted to the authenticated principal for this resource. Only populated when the 'expand[]=permissions' query parameter is provided. Keys are resource types (e.g., "organizations"), values are objects mapping permission names to boolean values indicating if the permission is granted.

Example response

{
  "items": [
    {
      "name": "org_admin",
      "label": "Organization Administrator",
      "description": "Full administrative access to all organization resources"
    }
  ],
  "permissions": {
    "organizations": {
      "read": true,
      "update": true
    },
    "users": {
      "read": true,
      "list": true
    }
  }
}

Changes

Changed in 3 of the 23 revisions of this API.16

Apr 20, 2026932699a5ea161See the full diff
- ○
  added the enum value total_count to the property items/ of the query request parameter expand[]
  request-parameter-property-enum-value-added
Mar 16, 2026d3d69f45bfed3See the full diff
- ○
  the endpoint scheme security OAuth2 was added to the API
  api-security-added
- ○
  the endpoint scheme security bearerAuth was added to the API
  api-security-added
- ○
  the endpoint scheme security org-management_bearerAuth was removed from the API
  api-security-removed
This revision also has 8 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Feb 6, 2026edd1b760a98912See the full diff
- ●
  deleted the header request parameter X-Request-ID
  request-parameter-removed
- ○
  the endpoint scheme security org-management_bearerAuth was added to the API
  api-security-added
- ○
  the endpoint scheme security svc-org-management_bearerAuth was removed from the API
  api-security-removed
This revision also has 82 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history