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"

Fields to expand in the response. Currently supports "permissions" to include the permissions field with the caller's permissions for the resource.

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
    }
  }
}