Skip to content

The open alternative to Salesforce, designed for AI.

Document default roles an app does not define (#29350)

Charles Bochetc0ad263b35a7
diff --git a/packages/twenty-docs/developers/extend/apps/config/roles.mdx b/packages/twenty-docs/developers/extend/apps/config/roles.mdx
index 8d4c8c3c2b3..18cb7fd72c0 100644
--- a/packages/twenty-docs/developers/extend/apps/config/roles.mdx
+++ b/packages/twenty-docs/developers/extend/apps/config/roles.mdx
@@ -226,12 +226,12 @@ 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()`. The identifier must match a role your app defines, or the build fails.
+- Setting `defaultRoleUniversalIdentifier` explicitly on `defineApplication()` is still supported for backward compatibility, but is deprecated in favor of `defineApplicationRole()`. It can also name a role your app does not define, such as the workspace custom application's built-in default role kept by `twenty app pull`; the build then cannot check that role, so it must exist in the target workspace.
- A role that workspace members or API keys can be assigned (`canBeAssignedToUsers` or `canBeAssignedToApiKeys`, both `true` when omitted) is a custom role and requires the **Organization plan or above**: on other plans the install is refused. Keep both `false` on roles that only your app and its agents run as.
### Agent roles
-The application role is what a workspace reviews when it installs your app, so it must cover everything the app itself can do. Any role you assign to an agent through `roleUniversalIdentifier` on `defineAgent()` must not grant more than the application role: no object action, field access, permission flag or row-level scope the application role lacks. If it does, the build fails with an error listing the excess grants. Roles your app ships for workspace members or API keys are not held to this rule, since the app never runs with them.
+The application role is what a workspace reviews when it installs your app, so it must cover everything the app itself can do. Any role you assign to an agent through `roleUniversalIdentifier` on `defineAgent()` must not grant more than the application role: no object action, field access, permission flag or row-level scope the application role lacks. If it does, the build fails with an error listing the excess grants. Roles your app ships for workspace members or API keys are not held to this rule, since the app never runs with them. The check needs the application role in your app's source, so it is skipped when the default role is defined elsewhere.
## Best practices