# Manage Access

An organization is the main Catalyst entity under which a set of Catalyst projects are onboarded.

:::tip Manage from the Catalyst console

Every operation on this page — inviting users, assigning roles, and creating or deleting API keys — can also be done from the Catalyst Web UI at [catalyst.diagrid.io](https://catalyst.diagrid.io).

:::

- User access — Invite administrators, editors, and viewers, and scope permissions to individual projects.
- Automation — Use API keys to authenticate via non-interactive automation through the Diagrid CLI.

## Manage users and roles

Administrators invite users and assign roles that apply to every project or to specific project scopes.

### Invite new users

Use the Diagrid CLI to invite new users:

```bash
diagrid product use catalyst

# Example: invite an admin
diagrid user create --email user@gmail.com --name user --role cra.diagrid:admin

# Example: invite a Consumer (developer access to API keys)
diagrid user create --email developer@gmail.com --name developer --role cra.diagrid:apiconsumer

# Example: invite an Operator (full project and subresource CRUD permissions)
diagrid user create --email operator@gmail.com --name operator --role cra.diagrid:apioperator
```

### Role definitions

Roles in Catalyst define a user's access level within the organization. The four roles are **cumulative** — each one includes every permission of the role before it and adds more:

- **Viewer** – Read-only access to projects and their resources. Cannot create or modify anything, and cannot access API keys, ID credentials, or metering data.
- **Consumer** – Viewer permissions, plus read access to ID credentials and metering data, full management of API keys, and the ability to run and manage workflow instances.
- **Operator** – Consumer permissions, plus the ability to create and update projects, and to create, update, and delete all project resources (workloads, components, subscriptions, resiliency policies, HTTP endpoints, service accounts, and more). Can list organization users but cannot manage them. Cannot delete projects (Admin only).
- **Admin** – Operator permissions, plus deleting projects, managing metering, and managing users and their roles. A global Admin also controls the organization: regions, cloud provider connections, billing, SSO connections, organization settings, and audit logs.

Roles can be applied at two levels:

- **Global** roles apply the role's permissions to every project in the organization.
- **Scoped** roles limit the role's permissions to one or more specific projects.

An Admin role scoped to a project administers that project only. It can delete the project, manage its metering, and invite, change, or remove users whose roles are all scoped to projects it administers. It cannot manage regions, cloud provider connections, billing, SSO connections, organization settings, or audit logs. Those need the global Admin role.

#### Permission matrix

The table below shows the access level each role has for every Catalyst resource:

- **Full** – view, create, edit, and delete
- **View** – read-only
- **None** – no access

| Resource | Viewer | Consumer | Operator | Admin (scoped) | Admin (global) |
| --- | :---: | :---: | :---: | :---: | :---: |
| Projects | View | View | Create & edit | Full | Full |
| Workloads, components, and configuration <sup>1</sup> | View | View | Full | Full | Full |
| ID credentials | None | View | View | View | View |
| Workflow instances <sup>2</sup> | View | Run & manage | Run & manage | Run & manage | Run & manage |
| [Service accounts](#service-accounts) and workload identity | None | None | Full | Full | Full |
| API keys | None | Full | Full | Full | Full |
| Metering data | None | View | View | Full | Full |
| Users and roles | None | None | View | Full <sup>3</sup> | Full |
| Regions and cloud provider connections | View | View | View | View | Full |
| Billing and SSO connections | None | None | None | None | Full |
| Audit logs | None | None | None | None | View |
| Organization profile | View | View | View | View | View & edit |

<sup>1</sup> Includes pub/sub brokers, KV stores, bindings, subscriptions, resiliency policies, HTTP endpoints, and other components.

<sup>2</sup> **Run & manage** covers scheduling, terminating, pausing, resuming, purging, raising events, and rerunning workflow instances.

<sup>3</sup> Only for users whose roles are all scoped to projects the Admin administers.

## Automate operations with API keys

API keys are named tokens with role assignments used for authenticating automation via the Diagrid CLI. After creation, include the token value with the `--api-key` flag to run commands under that key's permissions. Store the secret safely, for example:

```bash
catalyst_api_key=$(cat /secure-folder/diagrid-secret-token)

diagrid app list --api-key "${catalyst_api_key}"
```

Refer to the [Diagrid CLI reference](https://docs.diagrid.io/references/catalyst/cli-reference/apikey) for additional commands that accept the `--api-key` flag.

:::danger Important

API key secrets are only shown during creation. Copy the token before closing the dialog.

:::

### Generate API keys

Create API keys using the Diagrid CLI using the following reference. API responses include the secret token so make sure to copy it immediately because it is only displayed once.

- Global role format: `cra.diagrid:<role>` (`admin`, `viewer`, `apiconsumer`, or `apioperator`)
- Scoped role format: `cra.diagrid:<role>:projects:<project>` where `<role>` is `admin`, `apioperator`, `apiconsumer`, `viewer`, or the legacy `editor`, and `<projects>` is a comma-separated list of one or more projects

```bash
# Global admin key that expires in 24h (86400 seconds)
diagrid apikey create --name my-api-key --role cra.diagrid:admin --duration 86400

# Global API consumer key for automation, expires in 30 days (2,592,000 seconds)
diagrid apikey create --name my-automation-key --role cra.diagrid:apiconsumer --duration 2592000

# Scoped editor key for a specific project, expires in 30 days (2,592,000 seconds)
diagrid project list
diagrid apikeys create --name my-api-key --role cra.diagrid:editor:projects:<project> --duration 2592000
```

:::info

If no expiration period is configured when an API key is generated, the value is set to `never` (not recommended).

:::

<details>
  <summary>Create API keys from the console</summary>

  1. In the console sidebar, open **API Keys**.
  2. Select **+ Create API Key** and provide a unique name.
  3. Choose an expiration period (avoid `never` unless required).
  4. Assign roles. See [Role definitions](#user-roles).
  5. Select **Create**, then copy and securely store the token.
</details>

### Delete API keys

Delete API keys using the Diagrid CLI:

```bash
# Find the key ID
diagrid apikeys list

# Delete by ID
diagrid apikeys delete <my-api-key-id>
```

<details>
  <summary>Delete API keys from the console</summary>

  1. In the console sidebar, open **API Keys**.
  2. Locate the key to remove and open the action menu (three dots).
  3. Select **Delete API Key** and confirm.
</details>

## Automate operations with service accounts

An API key created with `diagrid apikey create` belongs to the user who created it. A service account is a non-human identity that owns its API keys instead, so a pipeline keeps working when the person who set it up changes role or leaves the organization.

Service accounts are managed with the Diagrid CLI and the [Catalyst control plane API](https://docs.diagrid.io/api/control-plane/catalyst). They do not appear in the Catalyst console.

### Create a service account

```bash
diagrid serviceaccount create ci-deployer \
  --owner platform-team@example.com \
  --role cra.diagrid:apioperator \
  --description "Deploys projects from CI"
```

`--owner`, `--role`, and `--description` are all required. `--owner` records the person or team accountable for the account and is a label, not a grant. `--role` takes any Catalyst role — `cra.diagrid:admin`, `cra.diagrid:apioperator`, `cra.diagrid:apiconsumer`, or `cra.diagrid:viewer` — either globally or scoped to projects in the same `cra.diagrid:<role>:projects:<project>` form used for [API keys](#api-keys). Role strings are matched exactly and are all lowercase.

Inspect and maintain accounts with the rest of the family:

```bash
diagrid serviceaccount list
diagrid serviceaccount get ci-deployer
diagrid serviceaccount update ci-deployer --role cra.diagrid:viewer
diagrid serviceaccount delete ci-deployer
```

### Issue API keys for a service account

Each key is created against the service account and named. Names must be unique within one service account, and that name is how you address the key afterwards — the CLI reference calls the argument `<apikey-id>`, but the value it expects is the name you chose with `--name`:

```bash
# Create a key that expires in 30 days (2,592,000 seconds)
diagrid serviceaccount apikeys create ci-deployer --name ci-token --expire-in-seconds 2592000

# List the keys the account holds
diagrid serviceaccount apikeys list ci-deployer

# Retrieve one key's token again
diagrid serviceaccount apikeys get ci-deployer ci-token

# Revoke one key
diagrid serviceaccount apikeys delete ci-deployer ci-token
```

Use the token exactly like an organization API key:

```bash
ci_token=$(diagrid serviceaccount apikeys get ci-deployer ci-token)

diagrid project list --api-key "${ci_token}"
```

Two differences from organization API keys are worth knowing:

- **The token stays retrievable.** `apikeys get` returns the token value again, so anyone who can read the service account can recover every token it holds. An organization API key shows its secret only at creation.
- **The role is stamped on the key when the key is issued.** A key carries the role the service account had at that moment. Changing the role with `diagrid serviceaccount update` does not change keys that already exist — reissue them to apply the new role.

Omit `--expire-in-seconds` and the key never expires, which is not recommended.