Skip to main content

Manage Catalyst organizations

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

👥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 an API consumer (developer access to API keys)
diagrid user create --email developer@gmail.com --name developer --role cra.diagrid:apiConsumer

# Example: invite an API operator (full project and subresource CRUD permissions)
diagrid user create --email operator@gmail.com --name operator --role cra.diagrid:apiOperator
Invite users from the console
  1. In the left sidebar of the Catalyst console, navigate to the Users tab.
  2. In the upper-right corner of the page, click the Invite User button.
  3. Provide the name of the user to invite.
  4. Enter the email address where the user invite will be sent. This email cannot be edited after the user is created.
  5. Set role assignments for the User. See Role definitions.
  6. In the lower-left corner, select Create to invite the user to the organization.

Role definitions​

Roles in Catalyst define the access level of the user within the organization. Roles can be applied at two levels: global or scoped. Global roles apply the role permissions to all projects in an organization. Scoped roles limit the selected role permissions to one or more specific project resources.

  • Admin – API Operator permissions + control over organization settings, users, roles, and API keys.
  • Viewer – Read-only access to projects and resources, without access to API keys or component credentials.
  • API Consumer – Viewer permissions + access to credentials and metering data.
  • API Operator – API Consumer permissions + ability to create and manage projects and project resources.

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 appid 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.