Manage Access

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

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.

👥User access

Invite administrators, editors, and viewers, and scope permissions to individual projects.

Manage users →

🔑Automation

Use API keys to authenticate via non-interactive automation through the Diagrid CLI.

Work with API keys →

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:

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 full control over the organization: deleting projects, managing users and roles, billing and metering, SSO connections, 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.

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
Projects	View	View	Create & edit	Full
Workloads, components, and configuration 1	View	View	Full	Full
ID credentials	None	View	View	View
Workflow instances 2	View	Run & manage	Run & manage	Run & manage
Service accounts and workload identity	None	None	Full	Full
API keys	None	Full	Full	Full
Metering data	None	View	View	Full
Users and roles	None	None	View	Full
Billing and SSO connections	None	None	None	Full
Audit logs	None	None	None	View
Organization profile	View	View	View	View & edit

¹ Includes pub/sub brokers, KV stores, bindings, subscriptions, resiliency policies, HTTP endpoints, and other components.

² Run & manage covers scheduling, terminating, pausing, resuming, purging, raising events, and rerunning workflow instances.

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:

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

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

Refer to the Diagrid CLI reference for additional commands that accept the --api-key flag.

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 editor or viewer and <projects> represents a comma-separated list of 1+ project(s)

# 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).

Create API keys from the console

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.
5. Select Create, then copy and securely store the token.

Delete API keys

Delete API keys using the Diagrid CLI:

# Find the key ID
diagrid apikeys list

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

Delete API keys from the console

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.

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. They do not appear in the Catalyst console.

Create a service account

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. Role strings are matched exactly and are all lowercase.

Inspect and maintain accounts with the rest of the family:

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:

# 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:

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.