# Source: https://docs.upsun.com/administration/users.md

# Administer users

Upsun offers fine-grained and flexible user permissions across projects and organizations.
When a user is added to a project, they are automatically added to your organization.

**Available add-on**: 

The Advanced User Management add-on offers [teams](https://docs.upsun.com/administration/teams.md), [MFA enforcement within an organization](https://docs.upsun.com/administration/security/mfa.md) and [single sign-on](https://docs.upsun.com/administration/security/sso.md). See how to [subscribe to this add-on](https://docs.upsun.com/administration/billing/add-on-subscription.md#advanced-user-management-add-on).

## Manage project access

If you have set up an external integration to GitHub, GitLab, or Bitbucket and your users can't clone the project locally,
see how to [troubleshoot source integrations](https://docs.upsun.com../integrations/source/troubleshoot.md).

### Project roles

A user can have one of the following roles to control their access at project level:

| Role           | View environment | Push code | Manage user access | Change settings | Execute actions on all environments |
|----------------|------------------|-----------|--------------------|-----------------|-------------------------------------|
| Project admin  | Yes              | Yes       | Yes                | Yes             | Yes                                 |
| Project viewer | Yes              | No        | No                 | No              | No                                  |

By default, organization owners have **Project admin** access on all of the projects within their organization.

### Environment type roles

An environment type (Production, Staging, and Development) groups one or more environments together so that you can manage access for all environments of that type:

- A role assigned to an environment type applies to all environments of that type.
- Only one environment per project can be of the type: Production.
  It is set automatically as the default branch and can't be overridden separately.
- You can change an environment's type (except for the Production environment).
- You can have multiple preview (staging and development) environments.

A user can have one of the following roles on an environment type which grants them permissions on all environments of this type:

| Role        | View environment | Force push | Push code | Branch environment | SSH access | Change settings | Execute actions |
|-------------|------------------|------------|-----------|--------------------|------------|-----------------|-----------------|
| Admin       | Yes              | Yes        | Yes       | Yes                | Yes        | Yes             | Yes             |
| Contributor | Yes              | No         | Yes       | Yes                | Yes        | No              | No              |
| Viewer      | Yes              | No         | No        | Yes                | No         | No              | No              |

To customize which roles can use SSH, set [`access` in your app configuration](https://docs.upsun.com/create-apps/image-properties/access.md).

### View a user's permissions across all of the projects in your organization

For each user, you can view a summary of their roles and permissions
across all projects in your organization.

 - Open the organization menu (your organization name in the upper-left).
 - Click **Users**.
 - For the user whose user permissions you want to view, click **More More**.
 - Click **Edit user**.

### Add a user to a project

To invite a user, you need to be a [project admin](#project-roles).

To add a user, follow these steps:

For example, if you want to add ``user1@example.com`` to the project as a project admin,
run the following command:

```bash {}
upsun user:add user1@example.com -r admin
```

If you want to add ``user2@example.com`` to the project as a contributor for Development environments
and a viewer for Staging environments,
run the following command:

```bash {}
upsun user:add user2@example.com -r development:contributor -r staging:viewer
```

 - Select the project where you want to add a new user.
 - Click Settings **Settings**.
 - Click **Access**.
 - Click **+ Add**.
 - Add the user’s details and choose their permissions.
 - Click **Save**.

The user has to create an account before they can access the project.
Once you add a user to a project, they receive an invitation email with instructions.

To apply SSH access changes after you add a user to a project,
[trigger a redeploy](https://docs.upsun.com../development/troubleshoot.md#force-a-redeploy).

### Manage project users

To manage user permissions on a project, you need to be a [project admin](#project-roles),
be an organization owner, or have the [**Manage users** permission for the organization](#organization-permissions).

To change user permissions, follow these steps:

If you want ``user1@example.com`` to be a viewer for Production environments
and a contributor for Development environments,
run the following command:

```bash {}
upsun user:update user1@example.com -r production:viewer,development:contributor
```

 - Select the project where you want to update user access.
 - Click Settings **Settings**.
 - Click **Access**.
 - Click the user you want to update permissions for.
 - Update environment type permissions, or click **Remove user**.
 - Click **Accept**.

To apply SSH access changes after you add a remove a user from a project or environment type,
[trigger a redeploy](https://docs.upsun.com../development/troubleshoot.md#force-a-redeploy).

### Remove a user from a project

To remove a user from a project, you need to be a [project admin](#project-roles),
be an organization owner, or have the [**Manage users** permission for the organization](#organization-permissions).

To remove a user, follow these steps:

 - Open the organization menu (your organization name in the upper-left).
 - Click **Users**.
 - For the user you want to remove, click **More More**.
 - Click on the **Projects** tab
 - For the project you want to remove them from, click **More More**.
 - Click **Remove from project**.
 - Click **Yes**.

To apply SSH access changes after changing a user's permissions for an environment type,
[trigger a redeploy](https://docs.upsun.com../development/troubleshoot.md#force-a-redeploy).

## Manage organization access

All users who are added to any project within an organization become members of that organization.
By default, such users have no [organization permissions](#organization-permissions).
You can also have organization users who aren't part of any projects.

Users who are a part of an organization with the **List projects** permission can see all projects in that organization at the organization's URL,
which takes the form `https://console.upsun.com/<ORGANIZATION_NAME>`.
They can only access projects they've been explicitly invited to.
For more information on project access control, see how to [manage project users](#manage-project-users).

### Organization permissions

As an organization owner or an organization user with the **Manage users** permission, you can invite other users to your organization and grant them the following permissions:

- **Admin** (`owner`):
  Manage the organization and access all organization permissions, including all listed below.
- **Manage billing** (`billing`):
  Add, remove, and edit billing information.
  Access invoices and vouchers.
  Users with this permission receive monthly invoices by email.
- **Manage users** (`members`):
  Add, remove, and edit organization-level users and permissions, except their own.
  Users with this permission can't grant other users permissions that they themselves don't have.
- **Create projects** (`projects:create`):
  Create new projects within the organization.
- **List projects** (`projects:list`):
  See all projects in an organization, even those the user can't access.

**Note**: 

Users with the **Manage users** (``members``) permission can add, edit, or remove any user’s permissions except their own.

Users with the **Manage billing** (``billing``) permission automatically are granted **List projects** (``projects:list``) permission.
That is, they are able to see all organization projects once given billing rights.

Users without any of these permissions can only access [projects where they're users](#project-roles).
They can't access or manage the rest of the organization.

Organization owners have all permissions within their organization.
Their permission level can't be edited.
Organization owners can't be removed from their organization,
except through an [ownership transfer](https://docs.upsun.com../administration/organizations.md#transfer-project-ownership).

#### Viewer permissions

A user is considered a viewer only if **all** of the following are true:

- Their organization-level permissions are limited to **view**, `project:list`, or **billing**  
- They are **not** an admin or contributor on any project  
- They do **not** have team-level access that grants admin permissions  

**Note**: 

If any of these conditions are not met, the user is counted as an **admin** for billing.

### Add a user to an organization

For example, to invite ``alice@example.com`` to the ``acme`` organization
with the **Manage billing** and **Create projects** permissions, run the following command:

```bash {}
upsun organization:user:add alice@example.com --org acme --permission billing,projects:create
```

 - Open the organization menu (your organization name in the upper-left).
 - Click **Users**.
 - Click **+ Invite users**.
 - Enter the users’ email addresses separated by commas.
 - Select which organization-wide permissions they should have.
 - Click **Invite**.

All users you invite receive an invitation email with instructions.

### Manage organization users

For example, to update the permissions for ``alice@example.com`` in your ``acme`` organization
so that she has only the **Manage billing** permission, run the following command:

```bash {}
upsun organization:user:update alice@example.com --org acme --permission billing
```

 - Open the organization menu (your organization name in the upper-left).
 - Click **Users**.
 - Next to the user you want to manage, click **More More**.
 - Click **Edit user**.

You see all the projects the user is a part of and their permissions in those projects.
You also see their permissions across the organization.
To edit their organization permissions, follow these steps:

 - Select or clear the checkboxes for the relevant permissions.
 - Click **Save**.
 - Click **Yes**.

### Remove a user from an organization

For example, to remove ``alice@example.com`` from your ``acme`` organization, run the following command:

```bash {}
upsun organization:user:delete alice@example.com --org acme
```

 - Open the organization menu (your organization name in the upper-left).
 - Click **Users**.
 - Next to the user you want to remove, click **More More**.
 - Click **Remove from organization**.

To delete users in bulk, select the users to remove and click **Remove users from organization**.

Remove a user from an organization will remove them from all projects they were a member of.