Create a new organization role

Required membership role: org admin. PBAC permission: role.create. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control

POST /v2/organizations/{orgId}/roles

Create a new organization role

cURL

curl --request POST \
  --url https://api.cal.com/v2/organizations/{orgId}/roles \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "color": "<string>",
  "description": "<string>",
  "permissions": [
    "eventType.read",
    "eventType.create",
    "booking.read"
  ]
}
'

201

{
  "status": "success",
  "data": {
    "id": "<string>",
    "name": "<string>",
    "type": "SYSTEM",
    "permissions": [
      "booking.read",
      "eventType.create"
    ],
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "color": "<string>",
    "description": "<string>",
    "organizationId": 123
  }
}

Headers

Authorization · string

For non-platform customers - value must be Bearer <token> where <token> is api key prefixed with cal_

x-cal-secret-key · string

For platform customers - OAuth client secret key

x-cal-client-id · string

For platform customers - OAuth client ID

Path Parameters

orgId · number · required

Body

application/json

name · string · required

Name of the role

Minimum string length: 1

color · string

Color for the role (hex code)

description · string

Description of the role

permissions · enum<string>[]

Permissions for this role (format: resource.action). On update, this field replaces the entire permission set for the role (full replace). Use granular permission endpoints for one-by-one changes.

Available options: *.*, role.create, role.read, role.readTeamRoles, role.readOrgRoles, role.update, role.delete, eventType.create, eventType.read, eventType.readTeamEventTypes, eventType.readOrgEventTypes, eventType.update, eventType.delete, team.create, team.read, team.readOrgTeams, team.readTeamSettings, team.readConferencing, team.readVerifiedResources, team.readMemberships, team.update, team.delete, team.invite, team.remove, team.listMembers, team.listMembersPrivate, team.changeMemberRole, team.impersonate, organization.create, organization.read, organization.readMemberships, organization.readManagedOrganizations, organization.readDelegationCredentials, organization.listMembers, organization.listMembersPrivate, organization.invite, organization.remove, organization.manageBilling, organization.changeMemberRole, organization.impersonate, organization.passwordReset, organization.editUsers, organization.update, organization.delete, booking.read, booking.readOrgBookings, booking.readRecordings, booking.update, booking.updateOrgBookings, booking.reassignOrgPastBookings, booking.readOrgAuditLogs, insights.read, workflow.create, workflow.read, workflow.readTeamWorkflows, workflow.update, workflow.delete, organization.attributes.read, organization.attributes.update, organization.attributes.delete, organization.attributes.create, organization.attributes.readSyncHistory, organization.attributes.editUsers, organization.attributes.readAuditLogs, routingForm.create, routingForm.read, routingForm.readTeamRoutingForms, routingForm.readOrgRoutingForms, routingForm.update, routingForm.delete, routingForm.readOrgAuditLogs, routingForm.readResponsePii, webhook.create, webhook.read, webhook.readOrgWebhooks, webhook.update, webhook.delete, availability.readTeamAvailability, availability.readOrgAvailability, availability.updateOrgAvailability, ooo.readOrgOoo, watchlist.create, watchlist.read, watchlist.update, watchlist.delete, featureOptIn.read, featureOptIn.update, organization.customDomain.create, organization.customDomain.read, organization.customDomain.update, organization.customDomain.delete

Example:

[
  "eventType.read",
  "eventType.create",
  "booking.read"
]

Response

201 - application/json

status · enum<string> · required

Available options: success, error

Example:

"success"

data · object · required

Show child attributes