Skip to main content

​
Overview

This guide is provider-agnostic. It assumes you (or another admin) have already configured at least one Secret Provider Credential. Pick your setup guide based on the path you want:
  • Static credentials: AWS · GCP
  • Workload Identity (rotation-aware): AWS · GCP
Use this guide to:
  • Grant the right permissions to org members.
  • Reference secrets from environment variables on your automations.
  • Verify everything resolves correctly at runtime.

​
Permissions (RBAC)

Three CrewAI Platform features are relevant when working with Secrets Manager:
  • secret_providers — controls access to the Secret Provider Credentials page.
  • workload_identity_configs — controls access to the Workload Identity page (only relevant if you use the WI path).
  • environment_variables — controls who can create or edit environment variables.
Each feature has two action levels: read and manage. Granting manage automatically implies read.

​
What to Grant

Owners automatically have full access to every feature. The default Member role intentionally excludes secret_providers and workload_identity_configs — admins must explicitly opt members in via a custom role.

​
How to Assign

  1. In CrewAI Platform, navigate to Settings → Roles. From this page you can create new roles, edit each role’s permissions, and assign roles to existing members of the organization.
  2. Click Create Role to make a new role, or open an existing role to edit its permissions.
  3. In the role’s permission editor, toggle the relevant features per the table above:
    • secret_providers: choose read if this role only needs to use existing credentials, or manage if it should also be able to create, edit, and delete credentials.
    • environment_variables: choose manage so the role can create environment variables that reference secrets.
  4. Save the role.
  5. Assign the role to the relevant members from the same Roles page (or the org Members list).

​
Referencing Secrets in Environment Variables

Once a provider credential exists and your role has the right permissions, you can reference managed secrets from any environment variable. In CrewAI Platform, navigate to Environment Variables and click Add Environment Variables. Fill the form:
  • Key — the name of the environment variable. Must start with a letter or underscore and contain only letters, numbers, and underscores. Conventionally uppercase, e.g. OPENAI_API_KEY.
  • Value Source — choose where the value comes from:
    • Direct Value — a plaintext value you type in. Use this when you do not want to involve a provider.
    • Use AWS default (or the equivalent for your provider) — uses the credential currently marked as the default for that provider type.
    • A specific named credential — select the credential by name. Use this if you have multiple credentials for the same provider (for example, aws-prod and aws-staging) and want to pick one explicitly.
  • Secret Name — the name of the secret in your provider. Once a credential is selected, this field offers autocomplete: start typing and CrewAI Platform queries your provider for matching secret names. Use the secret-name#json_key syntax to extract a single field from a structured (JSON) secret. For example, given a secret database-credentials with value {"username": "...", "password": "..."}, reference database-credentials#password to inject just the password.
    Azure Key Vault note: Azure secret names cannot contain underscores. CrewAI Platform automatically converts underscores in your Secret Name field to hyphens when calling Azure (e.g., db_password is sent as db-password).
Click Create to save the variable.
When editing an existing environment variable, leaving the Value field blank preserves the current value. This is intentional — it lets you change other fields (like the secret name or credential) without re-entering the value.

​
Verifying It Works

To verify end-to-end:
  1. Reference the environment variable on an automation, crew, or deployment exactly as you would any other environment variable.
  2. Deploy the automation.
  3. Trigger a run and confirm it completes successfully.

​
Rotation behavior depends on the credential path

If you need rotation-aware secrets (no re-deploy on rotation), use the Workload Identity path: AWS WI or GCP WI. The trade-off is more setup effort up front (registering CrewAI Platform as an OIDC provider in your cloud) but simpler operations long-term.
If the deploy or run fails with an error related to your secret, check the most common causes:

​
Next Steps