# Organizations

> Manage apps, people and access as a team

Organizations let your team own apps and manage access in one place. Invite people to your organization, organize them into groups, and assign each group a role on the apps they work on.

Every app on the Encore Platform belongs to an organization. When you sign up, Encore creates a personal organization named **Personal** for your own apps. Create a shared organization to work with a team.

With an organization, you can:

- **Own apps as a team:** Apps belong to the organization, so ownership stays with the team as people join and leave.
- **Manage membership centrally:** Invite people once and assign organization roles. Owners and Admins automatically get Admin access to every app the organization owns.
- **Assign access through groups:** Organize people into nested groups, such as Engineering, Backend and Frontend. Assign a group a role on an app to give that access to everyone in the group and its subgroups.
- **Define custom roles:** On the Enterprise plan, create app roles with different permissions for production and non-production environments.

## Create an organization

In the [Platform Dashboard](https://app.encore.dev), click **Create organization** above the app list, next to the owner filters.

Enter a name and a unique URL. The URL determines the address of your organization's pages: `app.encore.cloud/orgs/<url>`.

![Creating an organization](/assets/docs/orgs-create-org.png "Creating an organization")

You become the organization's Owner. To open the organization later, click the arrow next to its name above the app list.

The organization's sidebar contains **Overview**, **Apps**, **People**, **Groups**, **Roles**, **Billing** and **Settings**.

![An organization's overview](/assets/docs/orgs-org-overview.png "An organization's overview")

To create an app in the organization, click **New app** on its overview or select the organization as the owner when creating an app. To add an existing app, [transfer it to the organization](#move-an-app-into-an-organization).

## Organization roles

Each person has one organization role. This role determines what they can manage within the organization and whether they automatically receive access to its apps.

| Permission                                    | Owner | Admin | Billing manager | Member |
| --------------------------------------------- | ----- | ----- | --------------- | ------ |
| View the organization                         | Yes   | Yes   | Yes             | Yes    |
| Admin access to every app                     | Yes   | Yes   | No              | No     |
| Create apps                                   | Yes   | Yes   | No              | No     |
| Invite people and change their roles          | Yes   | Yes   | No              | No     |
| Manage groups                                 | Yes   | Yes   | No              | No     |
| Manage custom roles                           | Yes   | Yes   | No              | No     |
| Rename the organization                       | Yes   | Yes   | No              | No     |
| Manage billing                                | Yes   | Yes   | Yes             | No     |
| Assign the Owner role                         | Yes   | No    | No              | No     |
| Transfer apps into or out of the organization | Yes   | No    | No              | No     |
| Delete the organization                       | Yes   | No    | No              | No     |

Billing managers and Members do not receive app access through their organization role. Give them access through a [group](#groups) or invite them directly to an app.

An organization must have at least one Owner. Before removing or changing the role of the last Owner, assign the Owner role to someone else.

## Invite people

On the **People** page, enter an email address, select an organization role and click **Invite**.

Encore emails the invitation and lists it under **Pending invites** until it is accepted. To revoke a pending invitation, use its menu.

![The People page](/assets/docs/orgs-org-people.png "The People page")

Owners and Admins can change a person's role using the dropdown next to their name or remove them using the menu.

Removing someone revokes the app access they received through their organization role and group memberships. Any access granted through direct app invitations remains.

## Groups

Groups let you manage app access for multiple people at once. On the **Groups** page, create a group and add organization members to it. You can create a group at the top level or within another group.

Use a group's menu to rename it, move it into another group, add a subgroup or delete it.

![Nested groups](/assets/docs/orgs-org-groups.png "Nested groups")

A role assigned to a group applies to its members and everyone in its subgroups. In the example above, assigning a role to **Engineering** gives that role to Grace, who belongs directly to Engineering, and to everyone in **Backend** and **Frontend**.

A group's member count includes all members of its subgroups, with each person counted once.

Deleting a group also deletes its subgroups and removes the app access assigned to those groups. The people in those groups remain members of the organization.

### Give a group access to an app

Open the app's **Settings → Team** page. Under **Add to Team**, enter the group name, select a role and click **Add**.

![An app's team with group access](/assets/docs/orgs-app-team.png "An app's team with group access")

The team list shows:

- **Organization Owners and Admins:** Listed as **Admin · via** the organization. Manage their access through their organization roles.
- **Groups:** Each group assigned a role on the app, along with the number of people it gives access to. Use the dropdown to change its role or the menu to revoke its access.
- **People invited directly:** People given access through an email invitation to the app.

You can assign a group one of the [built-in app roles](/docs/platform/management/permissions), Admin, Member or Viewer, or one of the organization's [custom roles](#custom-roles).

Only groups from the organization that owns the app can be given access to it.

### How permissions are combined

A person can receive app access through their organization role, group memberships or a direct invitation. Their effective permissions depend on the roles they hold:

- **Built-in roles:** The most privileged role applies. For example, someone with Viewer access through one group and Member access through another has Member access.
- **Custom roles:** Permissions from all assigned custom roles are combined. Someone with two custom roles can perform any action allowed by either role.

## Custom roles

> **Note**
>
> Custom roles are available on the Enterprise plan. Other plans use the [built-in app roles](/docs/platform/management/permissions). [Contact sales](/book) to upgrade.

Built-in app roles grant the same permissions across all environments. Custom roles let you tailor permissions by environment. For example, you can let contractors deploy to staging while giving them only viewing access to production.

![The Roles page](/assets/docs/orgs-org-roles.png "The Roles page")

To create a custom role, open **Roles → New role**.

Each role contains rules that define access to a set of environments. Choose which environments a rule applies to by [environment type](/docs/platform/deploy/environments#environment-types):

- **All:** Every environment.
- **Production:** Environments of type `production`.
- **Non-production:** All other environments, including development and preview environments.

Only environments covered by a rule are visible through that role.

Each rule grants viewing access to the app, its code, and the selected environments' logs, traces, metrics, cron jobs, deploys and infrastructure. You can also enable these permissions:

| Permission            | Allows                                                                         |
| --------------------- | ------------------------------------------------------------------------------ |
| Deploy                | Start and cancel deploys                                                       |
| Change infrastructure | Approve, reject, continue and abort infrastructure changes, and edit resources |
| Manage secrets        | View secret values, create secrets and update them                             |
| Connect to databases  | Connect to databases as a reader, writer or admin                              |
| Manage buckets        | List, read, upload and delete bucket objects                                   |
| Call the API          | Call the app's API from the dashboard                                          |
| Run cron jobs         | Trigger cron jobs manually                                                     |

A role can contain multiple rules, but their environment selections cannot overlap. People assigned the role receive the permissions allowed by each rule in the environments it covers.

![Editing a custom role](/assets/docs/orgs-org-role-editor.png "Editing a custom role")

Once created, the role appears under **Custom roles** in the role dropdown on every app's **Team** page within the organization. Assign it to a group or a person invited directly, just like a built-in role.

When managing custom roles:

- **Choose a unique name:** Names must be unique within the organization and cannot be Admin, Member or Viewer.
- **Grant only permissions you hold:** You can only grant a role if you hold its permissions on every app where it is assigned.
- **Remove assignments before deleting:** Before deleting a role, remove it from every person and group on each app where it is assigned.
- **Duplicate an existing role:** Select **Duplicate** from a role's menu to use it as the starting point for a new role.

## Move an app into an organization

To transfer an app, open its **Settings → Ownership** page and click **Transfer app**.

Select the new owner, either an organization you belong to or a person identified by email, and enter the app's name to confirm.

![Transferring an app](/assets/docs/orgs-app-transfer.png "Transferring an app")

How the transfer completes depends on the destination:

- **An organization you own:** The transfer completes immediately.
- **Another organization:** One of its Owners must accept the transfer from the organization's overview.
- **A person:** The recipient must accept the transfer. The app then moves to their personal organization.

The app keeps its environments, deploys and data. When the transfer completes:

- **Direct access is removed:** Everyone invited directly to the app loses access. App access then comes from the destination organization's roles and groups.
- **Your access may change:** You lose access unless your role or group memberships in the destination organization grant it.
- **Billing moves to the new owner:** The app uses the new owner's subscription. A paid app can only be transferred to an owner with a paid subscription.

Pending transfers appear on the app's **Ownership** page. The person who started a transfer can cancel it there.

Transferring an app out of an organization requires the Owner role in that organization.

## Billing

Each organization has its own subscription. Owners, Admins and Billing managers can manage it on the organization's **Billing** page.

Apps created in the organization use its subscription. See [Plans & billing](/docs/platform/management/billing) for details about each plan.

## Organization settings

Owners and Admins can change the organization's name and URL on the **Settings** page. Changing the URL breaks existing links to the organization's pages.

Owners can also delete the organization from this page once all its apps have been transferred or deleted. Deleting an organization permanently removes its memberships and groups.

Personal organizations cannot be deleted.
