List Clerk organization roles

List organization roles in a connected Clerk application.

← All Clerk endpoints · Capability overview

GET/v1/clerk/organization-roles

https://api.vee3.io/v1/clerk/organization-roles

5 tokens

List organization roles in a connected Clerk application.

Authorization

Send your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

MCP

The same capability is available as an MCP tool on Vee3 hosted MCP.

Tool name

clerk.list_organization_roles

Parameters5 fields

clerk_instance_idstringOptional

Clerk instance id (ins_...) from clerk.get_connected_accounts. Omit to use the default connected account.

limitintegerOptional

Maximum number of results to return (1–500).

Default: 10 · min 1, max 500

offsetintegerOptional

Number of results to skip before returning.

Default: 0 · min 0

querystringOptional

Search by name or key.

order_bystringOptional

Sort order with optional + or - prefix (for example -created_at or name). Defaults to -created_at.

Response17 fields

organization_rolesarrayitems

15 fields

Organization roles in the connected Clerk application.

idstring

Clerk organization role id.

namestring

Role display name.

keystring

Role key used in memberships.

descriptionstring

Role description.

is_creator_eligibleboolean

Whether this role may be assigned as organization creator.

permissionsarrayitems

7 fields

Permissions assigned to this role.

idstring

Clerk organization permission id.

namestring

Permission display name.

keystring

Permission key used in role assignments.

descriptionstring

Permission description.

typestring

Permission type (system or custom).

created_atinteger

Unix timestamp in milliseconds when the permission was created.

updated_atinteger

Unix timestamp in milliseconds when the permission was last updated.

created_atinteger

Unix timestamp in milliseconds when the role was created.

updated_atinteger

Unix timestamp in milliseconds when the role was last updated.

total_countinteger

Total number of organization roles.

HTTP errors: clerk_connection_required, clerk_connection_not_found, clerk_connection_invalid, validation_error, unauthorized, payment_required

Example request

Python

import requests

url = "https://api.vee3.io/v1/clerk/organization-roles"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
}
params = {
    "limit": 10,
    "offset": 0,
    "query": "example"
}

response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
data = response.json()
print(data)

Example responses1 example

200Organization roles from a connected Clerk application.

organization_role_list.json

{
  "organization_roles": [
    {
      "id": "orgrl_2abc123",
      "name": "Admin",
      "key": "org:admin",
      "description": "Organization administrator",
      "is_creator_eligible": true,
      "permissions": [
        {
          "id": "orgperm_2abc123",
          "name": "Manage billing",
          "key": "org:sys_billing:manage",
          "description": "Manage organization billing",
          "type": "system",
          "created_at": 1710000000000,
          "updated_at": 1710000000000
        }
      ],
      "created_at": 1710000000000,
      "updated_at": 1710000000000
    }
  ],
  "total_count": 1
}