Cal.com Permission Documentation

This document maps existing role-based permission checks to the new PBAC (Permission-Based Access Control) system's permission strings in the format resource.action.

Permissions by Resource

Team Permissions

Event Type Permissions

Booking Permissions

Organization Permissions

API Key Permissions

Helper Functions and Utilities

The following helper functions are commonly used for permission checks:

Permission Level Enums

The codebase uses several enums to define permission levels:

MembershipRole Enum

enum MembershipRole {
  OWNER = "OWNER",
  ADMIN = "ADMIN",
  MEMBER = "MEMBER"
}

Entity Permission Level Enum

enum ENTITY_PERMISSION_LEVEL {
  NONE,
  USER_ONLY_WRITE,
  TEAM_READ_ONLY,
  TEAM_WRITE
}

Common Permission Patterns

1. Team Admin/Owner Check: Many operations require the user to be a team admin or owner.

   typescriptCopy

   if (!(await isTeamAdmin(ctx.user?.id, input.teamId))) throw new TRPCError({ code: "UNAUTHORIZED" });
   

2. Team Owner Check: Some operations (like changing an owner's role) require the user to be a team owner.

   typescriptCopy

   if (input.role === MembershipRole.OWNER && !(await isTeamOwner(ctx.user?.id, input.teamId)))
     throw new TRPCError({ code: "UNAUTHORIZED" });
   

3. Organization Admin Check: Operations within an organization require the user to be an organization admin.

   typescriptCopy

   if (user.profile?.organizationId && !user.organization.isOrgAdmin) {
     throw new TRPCError({ code: "FORBIDDEN", message: "org_admins_can_create_new_teams" });
   }
   

4. Entity Permission Check: Entity operations use permission level checks.

   typescriptCopy

   const permissionLevel = await getEntityPermissionLevel(entity, userId);
   return permissionLevel === ENTITY_PERMISSION_LEVEL.TEAM_WRITE || 
          permissionLevel === ENTITY_PERMISSION_LEVEL.USER_ONLY_WRITE;
   

5. Booking Access Control: Complex permission checks for retrieving bookings based on user roles and team/organization membership.

   typescriptCopy

   const membershipIdsWhereUserIsAdminOwner = (
     await prisma.membership.findMany({
       where: {
         userId: user.id,
         role: {
           in: ["ADMIN", "OWNER"],
         },
       },
       select: {
         id: true,
       },
     })
   ).map((membership) => membership.id);
   

Migration to PBAC

When migrating to the new PBAC system, these existing role-based checks should be replaced with permission string checks using the permissionMatches function:

import { permissionMatches } from "@calcom/features/pbac/types/permission-registry";

// Instead of:
if (!(await isTeamAdmin(ctx.user?.id, input.teamId))) throw new TRPCError({ code: "UNAUTHORIZED" });

// Use:
if (!permissionMatches("team.update", userPermissions)) throw new TRPCError({ code: "UNAUTHORIZED" });

Permission String Alternatives for Helper Functions

The following table provides permission string alternatives for common helper functions:

Entity Permission Functions and Resources

The following functions are used to check permissions for entities with userId and teamId properties:

Resources Used with Entity Permission Functions

These functions can be used with any entity that has userId and teamId properties. When migrating to PBAC, replace these checks with appropriate permission string checks:

// Instead of:
if (!(await canEditEntity(form, user.id))) throw new TRPCError({ code: "UNAUTHORIZED" });

// Use:
if (!permissionMatches("routingForm.update", userPermissions)) throw new TRPCError({ code: "UNAUTHORIZED" });

This allows for more granular permission control and the creation of custom roles with specific permissions.