List available roles

client.Organizations.ListRoles(ctx, organizationID, params) (*OrganizationListRolesResponse, error)

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

ParametersExpand Collapse

organizationID string

Organization ID or label identifier

minLength1

maxLength255

params OrganizationListRolesParams

Expand param.Field[[]string]optional

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

const OrganizationListRolesParamsExpandPermissions OrganizationListRolesParamsExpand = "permissions"

Scope param.Field[RoleScope]optional

Query param: Filter roles by scope (organization or zone level)

XClientRequestID param.Field[string]optional

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

formatuuid

ReturnsExpand Collapse

type OrganizationListRolesResponse struct{…}

List of available roles

Items []OrganizationListRolesResponseItem

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:

const RoleScopeOrganization RoleScope = "organization"

const RoleScopeZone RoleScope = "zone"

Permissions map[string, map[string, bool]]optional

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

package main

import (
  "context"
  "fmt"

  "github.com/keycardai/keycard-go"
)

func main() {
  client := keycard.NewClient(

  )
  response, err := client.Organizations.ListRoles(
    context.TODO(),
    "x",
    keycard.OrganizationListRolesParams{

    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Items)
}

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