# Roles and Permissions

## Overview

Bluebricks uses role-based access control (RBAC) to govern who can do what across your organization. Every user is assigned one account-level role that determines their permissions for all resources: clouds, collections, packages, environments, secrets, webhooks, and more.

{% hint style="info" icon="bookmark" %}
Account-level roles control what a user can do. Collection membership controls where they can do it. See [Owners and Members](https://bluebricks.co/docs/core-concepts/collections/owners-and-members) for collection-level access.
{% endhint %}

## Roles

Bluebricks defines five roles, ordered from most to least privileged: **Admin**, **Builder**, **Deployer**, **Viewer**, and **Guest**.

Read more about each role:

{% tabs %}
{% tab title="Admin" %}
**Admins have full access** to every resource and action in the organization. Admins manage users, configure organization settings, create API keys, and govern all collections, packages, and environments.

Assign this role to platform team leads and organization owners.
{% endtab %}

{% tab title="Builder" %}
**Builders can create and manage** infrastructure packages (artifacts and blueprints), collections, clouds, secrets, and webhooks. Builders can also initiate and manage deployments. They cannot invite or manage users, change organization settings, or create API keys.

Assign this role to infrastructure engineers who author and maintain IaC.
{% endtab %}

{% tab title="Deployer" %}
**Deployers can initiate runs and approve or apply plans.** Deployers have read access to the resources they need for deployment (collections, packages, clouds) but cannot create or modify infrastructure definitions. Deployers see only the **Deploy** and **Plan** pages.

Assign this role to operations engineers or CI/CD service accounts that run deployments without authoring IaC.
{% endtab %}

{% tab title="Viewer" %}
**Viewers have read-only access** to all resources. Viewers can browse collections, packages, environments, clouds, and organization data but cannot create, modify, or delete anything.

Assign this role to stakeholders, auditors, or team members who need visibility without write access.
{% endtab %}

{% tab title="Guest" %}
Minimal access. **Guests can only view deployment plans**. Guests see only the **Planner** page.

Assign this role to external reviewers or stakeholders who need to review a specific deployment plan without accessing any other part of the platform.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
New users who log in without a pre-assigned role are automatically assigned the **Deployer** role.
{% endhint %}

## How to invite new users or change roles

Users are managed via **Account Settings >** [**Users**](https://app.bluebricks.co/settings?tab=members) from there you can invite, change role or remove someone.

{% hint style="info" icon="user-key" %}
Only Admins can invite users and change roles.
{% endhint %}

<details open>

<summary>Invite new users</summary>

To invite a new user from account settings:

1. Click **Invite user**
2. Add the new user's **email**
3. Select the **desired role** from the dropdown
4. Click **Invite**

</details>

<details>

<summary>Change role of existing user</summary>

To change a users role from account settings:

1. Find the **user's name** in Account Settings > User
2. In the dropdown menu, select their new **role**

</details>

<details>

<summary>Remove user</summary>

To remove a user from account settings:

1. Find the user's name in Account Settings > User
2. Click the **three-dot menu** > click **remove**

</details>

<details>

<summary>Add a guest</summary>

The Guest role cannot be assigned manually through the invite flow.

</details>

## What each role can do

The tables below show every permission and which roles include it.

#### Cloud accounts

<table><thead><tr><th width="201.921875">Permission</th><th width="98.4296875">Admin</th><th width="95.765625">Builder</th><th width="109">Deployer</th><th width="99.71484375">Viewer</th><th width="96.03515625">Guest</th></tr></thead><tbody><tr><td>Create cloud accounts</td><td>Yes</td><td>Yes</td><td></td><td></td><td></td></tr><tr><td>View cloud accounts</td><td>Yes</td><td>Yes</td><td>Yes</td><td>Yes</td><td></td></tr><tr><td>Delete cloud accounts</td><td>Yes</td><td>Yes</td><td></td><td></td><td></td></tr></tbody></table>

#### Collections

<table><thead><tr><th width="202.2890625">Permission</th><th width="102.36328125">Admin</th><th width="104.8515625">Builder</th><th width="108.4375">Deployer</th><th width="102.19140625">Viewer</th><th width="93.7578125">Guest</th></tr></thead><tbody><tr><td>Create collections</td><td>Yes</td><td>Yes</td><td></td><td></td><td></td></tr><tr><td>View collections</td><td>Yes</td><td>Yes</td><td>Yes</td><td>Yes</td><td></td></tr><tr><td>Update collections</td><td>Yes</td><td>Yes</td><td></td><td></td><td></td></tr><tr><td>Delete collections</td><td>Yes</td><td>Yes</td><td></td><td></td><td></td></tr></tbody></table>

#### Packages (artifacts and blueprints)

<table><thead><tr><th width="209.44140625">Permission</th><th width="93.48046875">Admin</th><th width="95.4375">Builder</th><th width="107.83203125">Deployer</th><th width="95.79296875">Viewer</th><th width="95.12109375">Guest</th></tr></thead><tbody><tr><td>Create packages</td><td>Yes</td><td>Yes</td><td></td><td></td><td></td></tr><tr><td>View packages</td><td>Yes</td><td>Yes</td><td>Yes</td><td>Yes</td><td></td></tr><tr><td>Update packages</td><td>Yes</td><td>Yes</td><td></td><td></td><td></td></tr><tr><td>Delete packages</td><td>Yes</td><td>Yes</td><td></td><td></td><td></td></tr></tbody></table>

#### Environments and runs

<table><thead><tr><th width="220.79296875">Permission</th><th width="104.40234375">Admin</th><th width="98.32421875">Builder</th><th width="108.10546875">Deployer</th><th width="97.64453125">Viewer</th><th width="91.5">Guest</th></tr></thead><tbody><tr><td>Create environments</td><td>Yes</td><td>Yes</td><td>Yes</td><td></td><td></td></tr><tr><td>View environments</td><td>Yes</td><td>Yes</td><td>Yes</td><td>Yes</td><td></td></tr><tr><td>View run plans</td><td>Yes</td><td>Yes</td><td>Yes</td><td>Yes</td><td>Yes</td></tr><tr><td>Approve and apply runs</td><td>Yes</td><td>Yes</td><td>Yes</td><td></td><td></td></tr></tbody></table>

#### Secrets

<table><thead><tr><th width="218.02734375">Permission</th><th width="96.03515625">Admin</th><th width="100.640625">Builder</th><th width="109.05859375">Deployer</th><th width="98.4921875">Viewer</th><th width="93.25390625">Guest</th></tr></thead><tbody><tr><td>Create secrets</td><td>Yes</td><td>Yes</td><td></td><td></td><td></td></tr><tr><td>View secrets</td><td>Yes</td><td>Yes</td><td>Yes</td><td>Yes</td><td></td></tr><tr><td>Update secrets</td><td>Yes</td><td>Yes</td><td></td><td></td><td></td></tr><tr><td>Delete secrets</td><td>Yes</td><td>Yes</td><td></td><td></td><td></td></tr></tbody></table>

#### Webhooks

<table><thead><tr><th width="221.91015625">Permission</th><th width="93.546875">Admin</th><th width="97.55078125">Builder</th><th width="107.12109375">Deployer</th><th width="99.046875">Viewer</th><th width="93.4140625">Guest</th></tr></thead><tbody><tr><td>Create webhooks</td><td>Yes</td><td>Yes</td><td></td><td></td><td></td></tr><tr><td>View webhooks</td><td>Yes</td><td>Yes</td><td>Yes</td><td>Yes</td><td></td></tr><tr><td>Update webhooks</td><td>Yes</td><td>Yes</td><td></td><td></td><td></td></tr><tr><td>Delete webhooks</td><td>Yes</td><td>Yes</td><td></td><td></td><td></td></tr></tbody></table>

#### Users

<table><thead><tr><th width="225.94921875">Permission</th><th width="99.88671875">Admin</th><th width="97.72265625">Builder</th><th width="109.77734375">Deployer</th><th width="96.72265625">Viewer</th><th width="90.39453125">Guest</th></tr></thead><tbody><tr><td>Invite users</td><td>Yes</td><td></td><td></td><td></td><td></td></tr><tr><td>View users</td><td>Yes</td><td>Yes</td><td>Yes</td><td>Yes</td><td></td></tr><tr><td>Update user roles</td><td>Yes</td><td></td><td></td><td></td><td></td></tr><tr><td>Remove users</td><td>Yes</td><td></td><td></td><td></td><td></td></tr></tbody></table>

#### Organization and API keys

<table><thead><tr><th width="211.3046875">Permission</th><th width="101.65234375">Admin</th><th width="95.61328125">Builder</th><th width="111.828125">Deployer</th><th width="100.33203125">Viewer</th><th width="92.73046875">Guest</th></tr></thead><tbody><tr><td>View organization</td><td>Yes</td><td>Yes</td><td>Yes</td><td>Yes</td><td></td></tr><tr><td>Update organization settings</td><td>Yes</td><td></td><td></td><td></td><td></td></tr><tr><td>Create API keys</td><td>Yes</td><td></td><td></td><td></td><td></td></tr><tr><td>View API keys</td><td>Yes</td><td></td><td></td><td></td><td></td></tr><tr><td>Update API keys</td><td>Yes</td><td></td><td></td><td></td><td></td></tr></tbody></table>

{% hint style="info" %}
Long-lived API tokens have a **fixed set of permissions** that do not correspond to any user role. They cannot perform Admin-only actions such as inviting users or changing organization settings. See [API Authentication](https://bluebricks.co/docs/api/authenticate/authentication) for details.
{% endhint %}

#### Other resources

<table><thead><tr><th width="210.90625">Permission</th><th width="93.56640625">Admin</th><th width="97.21484375">Builder</th><th width="110.85546875">Deployer</th><th width="99.66015625">Viewer</th><th width="89.54296875">Guest</th></tr></thead><tbody><tr><td>View tasks</td><td>Yes</td><td>Yes</td><td>Yes</td><td>Yes</td><td></td></tr><tr><td>View rescue operations</td><td>Yes</td><td>Yes</td><td>Yes</td><td>Yes</td><td></td></tr><tr><td>View vendors</td><td>Yes</td><td>Yes</td><td>Yes</td><td>Yes</td><td></td></tr></tbody></table>

### Recommended role mapping for common teams

<table><thead><tr><th width="366.203125">Team function</th><th width="324.50390625">Recommended role</th></tr></thead><tbody><tr><td>Platform / DevOps lead</td><td>Admin</td></tr><tr><td>Infrastructure engineer</td><td>Builder</td></tr><tr><td>Application developer (deploys only)</td><td>Deployer</td></tr><tr><td>CI/CD service account</td><td>Deployer</td></tr><tr><td>Engineering manager / stakeholder</td><td>Viewer</td></tr><tr><td>External auditor or reviewer</td><td>Guest</td></tr></tbody></table>

## Account roles vs. collection membership

Bluebricks separates **what** a user can do (account-level role) from **where** they can do it ([collection membership](https://bluebricks.co/docs/core-concepts/collections/owners-and-members)).

* **Account-level role**: Assigned in **Account Settings > Users**. Defines the user's permissions across the entire organization. A user has exactly one account role.
* **Collection membership**: Assigned in **Collection Settings > Members**. Determines which collections a user can access and whether they are an owner or member of that collection.

Both layers must align for a user to act on a resource. For example, a user with the Builder role can create packages, but they can only deploy to collections where they are an assigned member.

{% hint style="info" icon="user-key" %}
Admins can manage any collection, even if they are not listed as a member or owner of that collection.
{% endhint %}

### How the layers work together

<table><thead><tr><th width="193.90234375">Scenario</th><th width="130.0546875">Account role</th><th width="128.92578125">Collection membership</th><th width="292.64453125">Result</th></tr></thead><tbody><tr><td>Platform lead needs full control</td><td>Admin</td><td>Owner</td><td>Full access to the organization</td></tr><tr><td>Engineer authors IaC for a team</td><td>Builder</td><td>Member</td><td>Can create and publish packages; can deploy to member collections</td></tr><tr><td>CI/CD pipeline deploys to production</td><td>Deployer</td><td>Member</td><td>Can run deployments in member collections; cannot modify packages or settings</td></tr><tr><td>Manager reviews infrastructure state</td><td>Viewer</td><td>Member</td><td>Can view all resources in member collections; cannot make changes</td></tr><tr><td>External reviewer checks a plan</td><td>Guest</td><td>n/a</td><td>Can view deployment plans only; no collection-level access needed</td></tr></tbody></table>

## What's next?

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>Set collection-level access in <strong>Owners and Members</strong></td><td><a href="https://454695563-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FL1aVoJ67VgVl8Uv83TuE%2Fuploads%2FxC2sGaWHhnyovno14pmQ%2FOwners%20and%20Members.png?alt=media&#x26;token=81f512bf-3dc7-49b1-b4af-725e365ab1d4">Owners and Members.png</a></td><td><a href="../core-concepts/collections/owners-and-members">owners-and-members</a></td></tr><tr><td>Create governance rules for collections with <strong>policies</strong></td><td><a href="https://454695563-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FL1aVoJ67VgVl8Uv83TuE%2Fuploads%2FQC4vqfOdlc0cD1F3hAzh%2FPolicies.png?alt=media&#x26;token=49d9bb0a-cabb-4bc1-ae3c-4f3f297cf805">Policies.png</a></td><td><a href="../core-concepts/collections/policies">policies</a></td></tr><tr><td>Set up <strong>Single-Sign-On</strong></td><td><a href="https://454695563-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FL1aVoJ67VgVl8Uv83TuE%2Fuploads%2FD0PCEri7o7YP1RvJEpYX%2FSSO.png?alt=media&#x26;token=ea852b14-8e41-4ff0-b8b6-e316331c1d7d">SSO.png</a></td><td><a href="setup-single-sign-on-sso">setup-single-sign-on-sso</a></td></tr><tr><td>Set the <strong>CLI authentication</strong></td><td><a href="https://454695563-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FL1aVoJ67VgVl8Uv83TuE%2Fuploads%2Fs4CatIl2wwNTuSZSfsct%2FAuthentication%20CLI.png?alt=media&#x26;token=05bfd360-27b4-4061-9f1b-ddf88f6a6d8c">Authentication CLI.png</a></td><td><a href="../bricks-cli/authentication">authentication</a></td></tr><tr><td>Learn about <strong>API token management</strong></td><td><a href="https://454695563-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FL1aVoJ67VgVl8Uv83TuE%2Fuploads%2F3CdhzY2Om4xQMX9EG581%2FAuthentication%20AI.png?alt=media&#x26;token=eba481c7-439c-487a-acb4-2a9afe8d1d93">Authentication AI.png</a></td><td><a href="https://bluebricks.co/docs/api/authenticate/authentication">https://bluebricks.co/docs/api/authenticate/authentication</a></td></tr></tbody></table>