Roles & Permissions - Twenty

A role is a permission set: which objects an app can read or write, which fields it can see, and which platform-level capabilities it can use. Every app's logic functions and front components inherit the permissions of the role marked with defineApplicationRole() (see The default function role below).

import {
  defineRole,
  PermissionFlag,
  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
} from 'twenty-sdk/define';

export default defineRole({
  universalIdentifier: '2c80f640-2083-4803-bb49-003e38279de6',
  label: 'My new role',
  description: 'A role that can be used in your workspace',
  canReadAllObjectRecords: false,
  canUpdateAllObjectRecords: false,
  canSoftDeleteAllObjectRecords: false,
  canDestroyAllObjectRecords: false,
  canUpdateAllSettings: false,
  canBeAssignedToAgents: false,
  canBeAssignedToUsers: false,
  canBeAssignedToApiKeys: false,
  objectPermissions: [
    {
      objectUniversalIdentifier:
        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
      canReadObjectRecords: true,
      canUpdateObjectRecords: true,
      canSoftDeleteObjectRecords: false,
      canDestroyObjectRecords: false,
    },
  ],
  fieldPermissions: [
    {
      objectUniversalIdentifier:
        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
      fieldUniversalIdentifier:
        STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.name.universalIdentifier,
      canReadFieldValue: false,
      canUpdateFieldValue: false,
    },
  ],
  permissionFlags: [PermissionFlag.APPLICATIONS],
});

The default function role

When you scaffold a new app, the CLI creates a default role file declared with defineApplicationRole():

import { defineApplicationRole, PermissionFlag } from 'twenty-sdk/define';

export const DEFAULT_ROLE_UNIVERSAL_IDENTIFIER =
  'b648f87b-1d26-4961-b974-0908fd991061';

export default defineApplicationRole({
  universalIdentifier: DEFAULT_ROLE_UNIVERSAL_IDENTIFIER,
  label: 'Default function role',
  description: 'Default role for function Twenty client',
  canReadAllObjectRecords: true,
  canUpdateAllObjectRecords: false,
  canSoftDeleteAllObjectRecords: false,
  canDestroyAllObjectRecords: false,
  canUpdateAllSettings: false,
  canBeAssignedToAgents: false,
  canBeAssignedToUsers: false,
  canBeAssignedToApiKeys: false,
  objectPermissions: [],
  fieldPermissions: [],
  permissionFlags: [],
});

defineApplicationRole() is a thin wrapper around defineRole() that flags the role used as your application's default at install time. Validation is identical to defineRole, but the build pipeline auto-wires its universalIdentifier into the application manifest's defaultRoleUniversalIdentifier — so you do not need to reference it from defineApplication yourself.

Notes:

Exactly one defineApplicationRole(...) is allowed per app — the manifest build will fail if it finds more than one.
Use defineRole() (not defineApplicationRole()) for any additional roles your app ships.
Setting defaultRoleUniversalIdentifier explicitly on defineApplication() is still supported for backward compatibility, but is deprecated in favor of defineApplicationRole().

Best practices

Start from the scaffolded role, then progressively restrict it — the default grants broad read access, which is rarely what you want in production.
Replace objectPermissions and fieldPermissions with the exact objects and fields your functions actually need.
permissionFlags control access to platform-level capabilities. Keep them minimal.
See a working example: hello-world/src/roles/function-role.ts.