Add Clerk role set roles

Add roles to a role set in a connected Clerk application.

← All Clerk endpoints · Capability overview

POST/v1/clerk/role-sets/{role_set_id}/roles

https://api.vee3.io/v1/clerk/role-sets/{role_set_id}/roles

8 tokens

Add roles to a role set 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.add_role_set_roles

Parameters5 fields

clerk_instance_idstringOptional

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

role_set_idstringRequired

Clerk role set id or key to retrieve, update, or modify.

role_keysarrayRequired

Role keys to add to the role set.

default_role_keystringOptional

Updated default role key after adding roles.

creator_role_keystringOptional

Updated creator role key after adding roles.

Response35 fields

role_setobject

34 fields

Updated role set summary.

idstring

Clerk role set id.

namestring

Role set display name.

keystring

Role set key.

descriptionstring

Role set description.

rolesarrayitems

8 fields

Roles included in this role set.

idstring

Role id within the role set.

namestring

Role display name.

keystring

Role key.

descriptionstring

Role description.

created_atinteger

Unix timestamp in milliseconds when the role was created.

updated_atinteger

Unix timestamp in milliseconds when the role was last updated.

members_countinteger

Number of members assigned this role in the role set.

has_membersboolean

Whether any members are assigned this role.

default_roleobject

8 fields

Default role for new members in this role set.

idstring

Role id within the role set.

namestring

Role display name.

keystring

Role key.

descriptionstring

Role description.

created_atinteger

Unix timestamp in milliseconds when the role was created.

updated_atinteger

Unix timestamp in milliseconds when the role was last updated.

members_countinteger

Number of members assigned this role in the role set.

has_membersboolean

Whether any members are assigned this role.

creator_roleobject

8 fields

Role assigned to organization creators in this role set.

idstring

Role id within the role set.

namestring

Role display name.

keystring

Role key.

descriptionstring

Role description.

created_atinteger

Unix timestamp in milliseconds when the role was created.

updated_atinteger

Unix timestamp in milliseconds when the role was last updated.

members_countinteger

Number of members assigned this role in the role set.

has_membersboolean

Whether any members are assigned this role.

typestring

Role set type.

created_atinteger

Unix timestamp in milliseconds when the role set was created.

updated_atinteger

Unix timestamp in milliseconds when the role set was last updated.

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/role-sets/{role_set_id}/roles"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "role_set_id": "orgroleset_2abc123",
    "role_keys": ["org:member"]
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
data = response.json()
print(data)

Example responses1 example

200Role set after adding roles.

role_set_with_roles.json

{
  "role_set": {
    "id": "rs_2abc123",
    "name": "Default",
    "key": "default",
    "description": "Default organization roles",
    "roles": [
      {
        "id": "orgrl_2member",
        "name": "Member",
        "key": "org:member",
        "description": "Organization member",
        "created_at": 1710000000000,
        "updated_at": 1710000000000,
        "members_count": 42,
        "has_members": true
      }
    ],
    "default_role": {
      "id": "orgrl_2member",
      "name": "Member",
      "key": "org:member",
      "description": "Organization member",
      "created_at": 1710000000000,
      "updated_at": 1710000000000,
      "members_count": 42,
      "has_members": true
    },
    "creator_role": {
      "id": "orgrl_2member",
      "name": "Member",
      "key": "org:member",
      "description": "Organization member",
      "created_at": 1710000000000,
      "updated_at": 1710000000000,
      "members_count": 42,
      "has_members": true
    },
    "type": "default",
    "created_at": 1710000000000,
    "updated_at": 1710000000000
  }
}