> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementum.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Roles & Permissions

> Manage access control through role-based permissions for secure enterprise workflows

## Overview

Roles & Permissions is the foundation of Elementum's security model. Best practice is to assign permissions through roles rather than to individual users. This approach ensures consistent access control, simplifies management across large teams, and keeps role assignments audit-ready for compliance reviews.

Elementum supports two permission scopes:

* **Organization-level** -- Grants access across all apps the user can reach. Use for administrative oversight roles such as IT administrators or compliance officers.
* **App-level** -- Grants access only to a specific app, element, or task and its related features. Use for department-specific or project-scoped roles.

<Warning>
  Organization-level permissions cascade down to all accessible apps. Assign org-level roles carefully and primarily for administrative oversight.
</Warning>

***

## Managed Roles

Managed roles are predefined roles with standard permission sets. Permissions are fixed; you manage **membership** only (users and groups). Organization managed roles and app managed roles are different sets—use the tabs below to compare them.

<Tabs>
  <Tab title="Organization roles">
    Open <img src="https://mintcdn.com/elementum/TFCVHNVI8zhq54sg/images/icons/settings.svg?fit=max&auto=format&n=TFCVHNVI8zhq54sg&q=85&s=3ffc43e8a0875412cc27335241aeb4c8" alt="Settings icon" className="inline-ui-icon" width="24" height="24" data-path="images/icons/settings.svg" /> **Org Settings** → **Roles & Permissions**, then select the **Organization roles** tab. The **Managed roles** list shows predefined organization roles; use **Manage membership** on each card to assign users and groups.

    * **Admin** -- Full access to Elementum Admin functions and organization settings, including company-wide configuration. Organization Admins also have view-only visibility into every App, Element, Task, and Table in the organization, and every record they contain, regardless of [object data access policies](/workflows/object-data-access) or per-record sharing. Edit, update, and delete permissions remain governed by the Admin's other role assignments. This org-wide visibility applies only to **Organization** Admins (assigned in **Org Settings**); Object-level admins (assigned in an individual App, Element, or Task) stay scoped to that Object.
    * **API Developer** -- Permissions to access and run Elementum APIs across the platform.
    * **App Admin** -- Create or edit apps, tasks, and elements at the organization level, within sharing and access policies that apply to what this user can reach.
    * **Bulk Import Admin** -- Use bulk import and bulk update from list views on apps, tasks, and elements.
    * **External Create** -- View, create, and update records; read and post to conversations on records the user can access (for external collaboration patterns).
    * **External Update** -- View and update records; read and post to conversations on accessible records according to access policies.
    * **Internal User** -- View, create, and update records, conversations, and attachments across apps, tasks, and elements the user can access.
    * **Service Requestor** -- Create service requests for users or groups that need to submit service requests through your workflows.

    <Info>
      **App Admin** at the organization level is not the same role as **App Admin** under **App roles**. Organization **App Admin** applies org-wide; app **App Admin** applies only within one app.
    </Info>
  </Tab>

  <Tab title="App roles">
    Open **Roles & Permissions** under **Security** in the app menu, then select the **App roles** tab.

    * **App Admin** -- Full administrative access to all features and settings within that app.
    * **Content Editor** -- Can create and manage content but cannot change app settings.
    * **Content Viewer** -- Read-only access to content and basic features.

    Start with managed roles when they fit your needs before creating custom alternatives.
  </Tab>
</Tabs>

***

## Custom Roles

Custom roles let you define any combination of permissions to match your organization's specific workflows.

### Create a Custom Role

1. Open <img src="https://mintcdn.com/elementum/TFCVHNVI8zhq54sg/images/icons/settings.svg?fit=max&auto=format&n=TFCVHNVI8zhq54sg&q=85&s=3ffc43e8a0875412cc27335241aeb4c8" alt="Settings icon" className="inline-ui-icon" width="24" height="24" data-path="images/icons/settings.svg" /> **Org Settings**.
2. Click **Roles & Permissions**.
3. Click **Create Custom Role**, enter a descriptive **Role Name**, and add a **Description** explaining the role's purpose.
4. Select the **Users** and **Groups** who should have this role.
5. Set permissions for each resource type. See [Permission Types](#permission-types) for the full list of granular options.

<Info>
  Custom roles can also be created directly on an app, element, or task. Click **Roles & Permissions** under the **Security** section of the object's menu. Object-scoped custom roles also expose [Auto Share Options](#auto-share-options), which are not available on organization-level custom roles.
</Info>

### Auto Share Options

Auto Share Options are only available when creating or editing a **custom role scoped to an object** (an app, element, or task) via **Roles & Permissions** under the **Security** section of that object's menu. They do not appear on organization-level custom roles.

When enabled, they automatically grant the custom role to a user the first time they interact with a record in one of the configured ways. The typical use case is making sure that someone who needs context on a record -- because they were assigned, mentioned, or added as a watcher -- has enough access to actually read and act on it, without an administrator manually sharing the record each time.

Because the role is assigned to the **user** (not just to that single record), every permission the role grants will apply across that object's scope. If the role grants broad access within the object, a single interaction on one record can silently widen a user's access across every record that object covers.

<Warning>
  Auto Share Options can unintentionally widen a user's access. Before enabling any trigger, make sure the role's permissions are tightly scoped to what a newly-interacting user actually needs -- typically read-only access to the related record and its conversations. Avoid combining Auto Share with roles that grant **Update Records**, **Delete Records**, **Bulk Update Records**, **Create Record Sharing**, or administrative permissions unless you explicitly want every triggering interaction to grant that level of access.
</Warning>

Each trigger controls a specific interaction. Enable only the triggers the role is designed for -- they are independent and additive.

* **When user is added as a watcher** -- The role is granted when the user starts watching a record (manually, or via automation). Use this to give watchers enough access to read the record they chose to follow. Good fit for lightweight view-oriented roles. Leaving this disabled prevents watchers from gaining any new access beyond what they already had.
* **When user is assigned to a record** -- The role is granted when the user becomes the assignee of a record. Use this to ensure assignees can actually work the record they own (view it, update required fields, post in its conversation). Pair with a role that grants the minimum editing permissions the assignee's job requires.
* **When user is @mentioned** -- The role is granted when the user is @-mentioned in a conversation or comment on a record. Use this to let mentioned users read the record and the conversation they were pulled into. Because anyone who can comment can trigger this, keep the role as read-only as possible to prevent comment-based privilege escalation.
* **When a record is shared with a user** -- The role is granted when a record is explicitly shared with the user via [record sharing](#relationships). Use this to give recipients of ad-hoc shares consistent access without every sharer having to reason about permissions.
* **When a record is approved** -- The role is granted when a record moves through an [approval process](/workflows/approval-processes) and receives an approval. Use this to give approvers continuing access to records they have signed off on -- for example, for audit trail, follow-up, or handoff to the next stage of the workflow. Because many approvers only need access during the approval itself, avoid pairing this trigger with a role that grants long-lived edit access unless post-approval access is the intent.

<Info>
  Auto Share Options layer on top of, but do not replace, your [object data access policies](/workflows/object-data-access). They are most effective when the auto-assigned role is narrowly scoped -- for example, a read-only role that grants **View Records**, **View Conversations**, **View Messages**, and **View Attachments** on the relevant object -- so that the trigger grants just enough access to do the work in front of the user.
</Info>

***

## Permission Types

Custom roles can include many granular permissions, grouped by resource type in the role editor. Use the **quick picker** at the top to apply common bundles (**View**, **Edit**, or **Admin** access) where available, then adjust individual permissions as needed.

Most resources follow a consistent **View / Create / Update / Delete** pattern:

* **View** -- Read-only access. Users can see the resource in the UI and reference it elsewhere, but cannot change it.
* **Create** -- Users can add new instances of the resource.
* **Update** -- Users can modify existing instances.
* **Delete** -- Users can permanently remove instances. Deletions are typically irreversible, so grant this permission to the smallest audience possible.

<Info>
  Follow the [principle of least privilege](#security-principles). Start by granting **View** only, then add **Create**, **Update**, or **Delete** as the role actually requires them. Administrative and configuration permissions -- especially those marked as sensitive below -- should be held by a narrow audience.
</Info>

<AccordionGroup>
  <Accordion title="Apps">
    Permissions for apps and their underlying building blocks -- **Objects** (apps, elements, and tasks), **Assignment Rules**, **Data Sources**, and **Tags**. These control who can see, build, or restructure apps in the organization or a specific app.

    * **Admin Access** -- Full administrative control within the scope of the role (org-wide for an organization role, app-wide for an app role). Grants every other permission in this category and overrides finer-grained settings. Assign only to users responsible for owning and configuring the scope.
    * **Create Objects**, **View Objects**, **Update Objects**, **Delete Objects** (Apps, Elements, Tasks) -- CRUD over the structural definitions of apps, elements, and tasks (fields, relationships, validations, and app configuration). **Create**, **Update**, and **Delete** are app-building permissions; grant them only to users who design or maintain apps. **View Objects** lets users see the structure without modifying it.
    * **View Apps** -- Lets users see which apps exist and open them, subject to other record- and access-level permissions. A prerequisite for most other app-scoped activity.
    * **Deploy Apps** -- Promote an app from one [environment](/administration/understand-organization-environments) to another. This is a separate permission from the **Update Objects** edit rights — a user with edit access on an app no longer automatically gains the ability to deploy it. Grant **Deploy Apps** in each environment that the user should be able to promote into, so deployment into Production can be controlled independently from deployment into Development or Staging. See [Deploy Apps between Environments](/administration/deploy-apps-between-environments) for the deployment workflow.
    * **Create Assignment Rules**, **View Assignment Rules**, **Update Assignment Rules**, **Delete Assignment Rules** -- Manage [assignment rules](/workflows/assignment-rules) that distribute work to users and groups. Mutating permissions can silently change how records are routed and who gets notified, so limit them to workflow owners.
    * **View Data Sources** -- See the data sources (such as [CloudLinks](/administration/setup-cloudlink)) configured for the scope. Required to reference those data sources when building apps or automations.
    * **Create Tags**, **Update Tags**, **Delete Tags** -- Manage the organization's tag library used to label and filter records.
  </Accordion>

  <Accordion title="Attachments">
    Permissions for files attached to records, conversations, and messages. Because attachments often contain the most sensitive data in a record (contracts, screenshots, PII), treat these permissions as record-data permissions.

    * **Create Attachments** -- Upload new files to records or conversations.
    * **View Attachments** -- Download and preview attached files. Grant only to audiences who should see the content of those files -- not everyone who can view a record needs attachment access.
    * **Update Attachments** -- Replace or modify attached files.
    * **Delete Attachments** -- Permanently remove attachments. Deletions cannot be undone.
  </Accordion>

  <Accordion title="Conversations">
    Permissions for **Conversations** (threaded discussions on records) and the individual **Messages** posted inside them. Conversations frequently contain the most candid commentary on a record, so handle view permissions with the same care as records.

    * **Create Conversations** -- Start a new conversation on a record.
    * **View Conversations** -- See that a conversation exists and open it. Does not imply permission to read individual messages if **View Messages** is withheld.
    * **Update Conversations** -- Modify conversation metadata (title, participants, status).
    * **Delete Conversations** -- Permanently remove a conversation and its messages.
    * **Create Messages** -- Post a new message in a conversation.
    * **View Messages** -- Read the content of messages. Withhold this to keep a user aware that a conversation exists without exposing its contents.
    * **Update Messages** -- Edit messages. Typically only the author or an admin should hold this.
    * **Delete Messages** -- Remove individual messages. Deletions are permanent.
  </Accordion>

  <Accordion title="Automations">
    Permissions for the three automation surfaces: generated **Documents**, **Workflows** built in Flow, and **Data Mines** that watch warehouse data.

    **Documents**

    * **Create Documents**, **View Documents**, **Update Documents**, **Delete Documents** -- Manage document generation templates used by automations. Templates can embed record data and attachments in outbound files, so **Update** and **Delete** are configuration-level permissions.

    **Workflows**

    * **Create Workflows**, **View Workflows**, **Update Workflows**, **Delete Workflows** -- Manage [automation workflows](/workflows/automation-system) in Flow. Mutating permissions allow users to change business logic that runs without further approval, so grant them to workflow owners only.

    **Data Mines**

    * **Create Data Mines**, **View Data Mines**, **Update Data Mines**, **Delete Data Mines** -- Manage [Data Mines](/data/data-mining), the feature that watches CloudLink-backed tables on a schedule and triggers automations when row state changes. **Update** and **Delete** can silently change or stop downstream automations.
  </Accordion>

  <Accordion title="Relationships">
    Permissions for linking data together and for sharing individual records.

    * **Create Element Relations**, **Delete Element Relations** -- Add or remove relationships between elements so records can be linked and joined across objects. See [showing relationships](/data/showing-relationships).
    * **Create Record Sharing**, **Delete Record Sharing** -- Grant or revoke access to an **individual record** for specific users or groups, on top of the broader [object data access policies](/workflows/object-data-access). This is the fastest path to widen access to a single record, so limit **Create Record Sharing** to users who understand the data they are sharing.

    <Warning>
      **Create Record Sharing** bypasses access-policy controls for the records it is used on. Grant it only to users who are expected to share data externally or with other teams.
    </Warning>
  </Accordion>

  <Accordion title="Records">
    Permissions for the records themselves, along with the features that govern what records users can see (**Data Access Policies**) and who can read past activity (**Activity Logs**).

    * **Create Records**, **View Records**, **Update Records**, **Delete Records** -- Standard CRUD on records within the scope. Subject to any [object data access policies](/workflows/object-data-access) that restrict which records the user can see.
    * **Bulk Update Records** -- Make the same change to many records at once from a list view. Bulk operations are hard to reverse and harder to audit one row at a time; grant only to power users who are accountable for the data.
    * **Create Data Access Policies**, **View Data Access Policies**, **Update Data Access Policies**, **Delete Data Access Policies** -- Manage the rules that determine which records users and groups can access. Changes here directly change who can see which records -- treat these as security-critical.
    * **View Activity Logs** -- Read the [activity log](/administration/activity-log) for the scope. Because activity logs can reveal sensitive actions (who viewed what, when), limit this to auditors and administrators.
    * **Create Document Models**, **View Document Models**, **Update Document Models**, **Delete Document Models**
    * **View Tags** -- See tags applied to records. Pair with **Create/Update/Delete Tags** under **Apps** for users who maintain the tag library.

    <Warning>
      **Data Access Policies** define who can see what. Mutating permissions in this group can widen record access across the organization in a single change. Keep **Create**, **Update**, and **Delete Data Access Policies** on a short list of administrators.
    </Warning>
  </Accordion>

  <Accordion title="Analytics">
    Permissions for charts, dashboards, and the analytics building blocks that feed them. **Charts** and **Dashboards** can expose aggregated views of record data even when users cannot see the underlying records, so treat viewing permissions here as data-visibility permissions.

    * **Create Analytics Events**, **View Analytics Events** -- Manage analytics events, the telemetry and usage records captured by the platform. Each event includes an event name, platform, optional field/section/value context, device metadata (type, OS, manufacturer), session ID, user agent, and IP address. **View Analytics Events** lets a user query stored events (required to access event data via the API); **Create Analytics Events** controls the ability to record new events into the platform. Only available on **organization-level** custom roles.
    * **Create Charts**, **View Charts**, **Update Charts**, **Delete Charts** -- CRUD for individual charts.
    * **Create Dashboards**, **View Dashboards**, **Update Dashboards**, **Delete Dashboards** -- CRUD for dashboards that group charts together. Dashboards can be shared broadly, so deletion of a widely used dashboard should be limited to dashboard owners.
    * **View Metrics** -- See platform metrics surfaced in analytics.
    * **View Skills** -- See the [agent skills](/ai-agents/agents-skills) available in the Skills Directory. Required for users who build or audit agents that call skills.
    * **View Analysts**, **Update Analysts** -- Manage **Analysts**, predefined roles that encapsulate specific skills and responsibilities to standardize how certain types of work are scoped and assigned within an organization. **View Analysts** lets a user see Analyst role definitions; **Update Analysts** lets a user modify those definitions.
  </Accordion>

  <Accordion title="AI Providers">
    Permissions for the authenticated connections to external AI model services (OpenAI, Anthropic, Google Gemini, Snowflake Cortex, Amazon Bedrock, and Custom OpenAI-compatible endpoints) and the connectors that route traffic to them. Providers hold credentials and drive AI spend, so treat these permissions as infrastructure-level.

    **Providers** hold the credentials for an external AI service. **Connectors** reuse a provider's credentials to bind a specific model or app to a specific feature without duplicating secrets. Separating the two permissions lets administrators own credential management centrally while still allowing other users to wire the same Snowflake, OpenAI, Anthropic, Bedrock, or custom-endpoint account into different models or features.

    **Providers**

    * **Create AI Provider** -- Register a new AI provider and its credentials.
    * **View AI Provider** -- See which providers are configured (credentials remain hidden).
    * **Update AI Provider** -- Modify a provider's configuration, including credentials and routing.
    * **Delete AI Provider** -- Remove a provider. Any agent, service, or automation pointing at the provider will stop working.

    **Connectors**

    * **Create AI Provider Connector**, **View AI Provider Connector**, **Update AI Provider Connector**, **Delete AI Provider Connector** -- Manage the connectors that reuse an existing provider's credentials to drive a specific model, app, or feature (for example, a CloudLink-backed Cortex provider bound to a specific feature). Connectors -- and the per-feature CloudLink binding they carry -- are where data residency, routing, and spend attribution are tuned, so they remain sensitive even for users who cannot create new providers.

    <Warning>
      Creating or updating an AI provider stores credentials that the platform will use to make outbound calls that incur cost. Limit these permissions to administrators responsible for the AI spend budget and vendor relationships. **Create/Update AI Provider Connector** can redirect AI traffic and shift data residency or cost attribution without touching provider credentials, so scope those permissions just as carefully.
    </Warning>
  </Accordion>

  <Accordion title="Agents">
    Permissions for [AI agents](/ai-agents/ai-overview) -- the reusable AI components that execute tasks inside workflows.

    * **Create Agents** -- Build new agents.
    * **View Agents** -- See which agents exist and review their configuration.
    * **Update Agents** -- Modify an agent's prompt, tools, providers, or data sources. Because an agent's behavior is defined by its configuration, **Update Agents** effectively controls what the agent does at runtime.
    * **Delete Agents** -- Remove an agent. Any workflow, automation, or skill that depends on the agent will stop working.
  </Accordion>

  <Accordion title="Users">
    Administrative permissions for managing users, tokens, roles, org structure, service accounts, and SCIM. This is the highest-privilege category -- several of these permissions can be used to escalate access to the entire organization.

    * **Create Organization Users**, **Update Organization Users** -- Invite new users and modify existing user records. Subject to the [User Invite Policy](#user-invite-policy). **Update Organization Users** includes profile information and, for admins, role and group membership.
    * **Delete Groups** -- Permanently delete groups. (Other group CRUD is under the **Groups** category.)
    * **Create Roles**, **View Roles**, **Update Roles**, **Delete Roles** -- Manage the role definitions themselves. A user who can **Update Roles** can effectively grant themselves any permission.
    * **Create Object Level Roles**, **View Object Level Roles**, **Update Object Level Roles**, **Delete Object Level Roles** (Apps, Elements, Tasks) -- Manage roles that are scoped to a single app, element, or task. Useful for giving an app owner role-admin rights inside their app without org-wide role admin.
    * **Create Organization Structures**, **Update Organization Structures**, **Delete Organization Structures** -- Manage the organization's [reporting hierarchy](/administration/org-structure) (managers, departments, job titles). This data drives dynamic approval chains and manager-based routing, so incorrect values can misdirect approvals.
    * **Create OAuth Tokens**, **Delete OAuth Tokens** -- Manage API tokens issued against the user's account for [Elementum API](/api-reference/api-introduction) access. Tokens are bearer credentials: anyone who holds the token can act as the issuing user.
    * **Create Service Accounts**, **View Service Accounts**, **Update Service Accounts** -- Manage [service accounts](/administration/service-accounts) used by automations and integrations. Service accounts can hold powerful roles, so these permissions grant the ability to create and configure non-human principals.
    * **SCIM Integration** -- Configure and run [SCIM provisioning](/administration/sso-saml-setup#scim-provisioning), which synchronizes users and groups from your identity provider. A misconfigured SCIM connection can create, disable, or reassign accounts at scale.

    <Warning>
      **Create Roles**, **Update Roles**, **Create Service Accounts**, **Update Service Accounts**, and **SCIM Integration** can each be used to escalate privileges across the organization. Reserve them for a small set of security administrators and review assignments regularly.
    </Warning>
  </Accordion>

  <Accordion title="Groups">
    Permissions for managing [org groups](/administration/groups) used to grant access and send notifications at scale.

    * **Create Groups** -- Add new groups and set their type and visibility.
    * **View Groups** -- See the groups that exist and their membership.
    * **Update Groups** -- Modify group settings (name, type, visibility, membership). **Update Groups** can silently add members to a group that grants access, so treat it as an access-granting permission.

    <Info>
      **Delete Groups** is listed under the [Users](#users) category.
    </Info>
  </Accordion>

  <Accordion title="Cloudlinks">
    Permissions for [CloudLink](/administration/setup-cloudlink) -- the connection to external data warehouses such as Snowflake, BigQuery, and Databricks -- and the warehouse-backed **Elements** and **Procedures** used in Elementum.

    * **View Cloudlink Explore** -- Use the CloudLink Explore interface to browse warehouse schemas and sample data. This exposes raw warehouse content, so grant it only to users allowed to browse underlying data.
    * **Create Elements**, **View Elements**, **Update Elements**, **Delete Elements** -- CRUD on CloudLink-backed elements that project warehouse tables into Elementum.
    * **Create Procedures**, **View Procedures**, **Update Procedures**, **Delete Procedures** -- Manage warehouse stored procedures imported into Elementum so automations can call them.
  </Accordion>

  <Accordion title="Services">
    Permissions for [service requests](/workflows/tasks) -- work items submitted through request forms.

    * **Create Service Requests** -- Submit new service requests.
    * **View Service Requests** -- See requests visible to the user.
    * **Update Service Requests** -- Modify open requests. Typically held by fulfillment teams.
    * **Delete Service Requests** -- Permanently remove a request. Keep this narrow to preserve an audit trail.
  </Accordion>

  <Accordion title="Marketplace">
    Permissions for publishing to and installing from the Elementum Marketplace.

    * **View Marketplace Apps** -- Browse the marketplace and see the apps available for installation.
    * **Create Marketplace Apps** -- Install marketplace apps into your organization.
  </Accordion>

  <Accordion title="Service Level Agreements">
    Permissions for [service level agreements](/workflows/service-level-agreements) that track response and resolution targets.

    * **Create Service Level Agreements**, **View Service Level Agreements**, **Update Service Level Agreements**, **Delete Service Level Agreements** -- Manage SLA definitions applied to records. Mutating SLAs retroactively can affect breach reporting, so limit **Update** and **Delete** to SLA owners.
  </Accordion>
</AccordionGroup>

Users can hold multiple roles simultaneously -- permissions are additive across all assigned roles. When two roles disagree, the **most permissive** setting wins. There is no "deny" override and no role hierarchy: assigning a read-only role on top of an edit-granting role does not remove edit access.

### Enforce read-only access for specific users

Because permissions are additive, simply adding a user to a read-only role does **not** restrict them if they also belong to a role that grants `Update Records` -- including the **Internal User** organization role or the **Content Editor** app role, which are commonly assigned to the system-managed **All Users** or **Internal Users** [groups](/administration/groups). System-managed groups cannot have their membership edited, so you cannot "remove" a user from All Users or Internal Users.

To make a specific set of users read-only without affecting everyone else:

1. **Audit edit-granting roles.** In **Org Settings** → **Roles & Permissions**, identify which roles grant `Update Records` (or other write permissions) and which users or groups are members. Pay particular attention to roles whose membership includes the system-managed **All Users** or **Internal Users** groups.
2. **Scope edit access app-by-app instead of org-wide.** If the **Internal User** org role is granting edit access broadly, remove that role from the users who should be read-only, and grant edit access at the app level only -- through a custom group assigned to the **Content Editor** app role (or a custom app role with `Update Records`) on the specific apps where editing is intended.
3. **Create a custom "editors" group** for users who do need edit access on a given app, and assign the edit-granting app role to that group only.
4. **Leave read-only users with view-only roles.** Once read-only users are no longer members of any role that grants `Update Records`, the view-only role (for example, **Content Viewer** at the app level) takes effect. No further action on All Users or Internal Users is required.

<Info>
  You cannot edit membership of **All Users**, **Internal Users**, or **External Users**. These groups are maintained automatically by Elementum. See [Groups](/administration/groups#system-managed-groups) for which group properties Org Admins can change.
</Info>

***

## User Invite Policy

The **User Invite Policy** is an organization-level setting that controls which users can invite new people into the organization. Find it in <img src="https://mintcdn.com/elementum/TFCVHNVI8zhq54sg/images/icons/settings.svg?fit=max&auto=format&n=TFCVHNVI8zhq54sg&q=85&s=3ffc43e8a0875412cc27335241aeb4c8" alt="Settings icon" className="inline-ui-icon" width="24" height="24" data-path="images/icons/settings.svg" /> **Org Settings** → **General**.

The policy applies on top of the CREATE\_ORGANIZATION\_USERS permission. Users must first have this permission, and the policy then further restricts what they can do.

<Info>
  Users with the **ADMIN** permission always bypass the policy and can invite anyone regardless of the setting.
</Info>

### Policy Options

<Tabs>
  <Tab title="Only Admins can invite">
    The most restrictive setting. Only administrators can invite new users.

    **Behavior:**

    * **Admins**: Can invite any user (any email domain)
    * **Non-admins**: Cannot invite anyone, even if they have CREATE\_ORGANIZATION\_USERS permission. Requests are rejected with a validation error.

    **Use case**: Organizations that want centralized control over user provisioning.
  </Tab>

  <Tab title="Allow any email domain">
    The most permissive setting. Any user with appropriate permissions can invite anyone.

    **Behavior:**

    * **Admins**: Can invite any user
    * **Non-admins** (with CREATE\_ORGANIZATION\_USERS): Can invite users from any email domain with no restrictions

    **Use case**: Organizations that want to let team members quickly onboard external collaborators.
  </Tab>

  <Tab title="Allowed email domains only">
    A balanced setting that allows delegation while maintaining domain restrictions.

    **Behavior:**

    * **Admins**: Can invite any user
    * **Non-admins** (with CREATE\_ORGANIZATION\_USERS): Can only invite users whose email domain is on the organization's approved managed domains list. Attempts to invite users from non-approved domains are rejected.

    **Use case**: Organizations that want to allow team members to invite colleagues while preventing invitations to external domains.
  </Tab>
</Tabs>

<Warning>
  The User Invite Policy only affects **inviting new users** into the organization. Adding existing organization users to resources like customer chat channels is controlled separately by the UPDATE\_CONVERSATIONS permission.
</Warning>

***

## Manage Roles

1. Open **Roles & Permissions** for the scope you need: **Org Settings** → **Roles & Permissions** for organization roles, or **Roles & Permissions** under **Security** in an app menu for that app’s roles.
2. Click **Manage Role** on any role to add or remove users and groups.
3. For custom roles, modify permissions and settings as business needs change.
4. Remove custom roles that are no longer needed. Managed roles cannot be deleted.

<Info>
  For organizations with multiple [environments](/administration/understand-organization-environments), role membership is tracked per environment. See [Environment-specific role membership](/administration/understand-organization-environments#environment-specific-role-membership) for how to grant a role in a specific environment.
</Info>

***

## Best Practices

### Security Principles

* **Principle of least privilege** -- Grant only the minimum permissions necessary for users to perform their job functions.
* **Separation of duties** -- Ensure critical functions require multiple roles or approvals.
* **Regular audits** -- Periodically review role assignments and permissions to confirm they remain appropriate.
* **Descriptive naming** -- Use clear, descriptive role names that indicate purpose and scope.

### Common Security Patterns

<AccordionGroup>
  <Accordion title="Role Segregation">
    Separate roles by function rather than hierarchy. Create roles based on job responsibilities, avoid overly broad permissions, and prefer multiple specific roles over one broad role.
  </Accordion>

  <Accordion title="Temporary Access">
    Use custom roles for temporary or project-based access. Create time-limited roles for contractors, remove access when projects complete, and regularly clean up unused roles.
  </Accordion>

  <Accordion title="Emergency Access">
    Plan for emergency access scenarios. Designate emergency administrators, document emergency procedures, and test emergency access regularly.
  </Accordion>
</AccordionGroup>
