List available roles

GET/organizations/{organization_id}/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

Path ParametersExpand Collapse

organization_id: string

Organization ID or label identifier

minLength1

maxLength255

Query ParametersExpand Collapse

expand: optional array of "permissions" or "total_count"

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.

Accepts one of the following:

"permissions"

"total_count"

scope: optional RoleScope

Filter roles by scope (organization or zone level)

Accepts one of the following:

"organization"

"zone"

Header ParametersExpand Collapse

"X-Client-Request-ID": optional string

formatuuid

ReturnsExpand Collapse

items: array of object { description, label, name, scope }

List of roles

description: string

Detailed description of the role and its permissions

maxLength500

label: string

Human-readable display name for the role

maxLength128

name: string

Internal identifier for the role (e.g., org_admin, zone_manager)

scope: RoleScope

The scope at which this role can be assigned (organization or zone)

Accepts one of the following:

"organization"

"zone"

permissions: optional map[map[boolean]]

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.

List available roles

curl https://api.keycard.ai/organizations/$ORGANIZATION_ID/roles

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

Returns Examples

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