> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Using the Secrets Manager

> Manage permissions and reference managed secrets from environment variables in CrewAI Platform

## 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](/en/enterprise/features/secrets-manager/aws) · [GCP](/en/enterprise/features/secrets-manager/gcp)
* Workload Identity (rotation-aware): [AWS](/en/enterprise/features/secrets-manager/aws-workload-identity) · [GCP](/en/enterprise/features/secrets-manager/gcp-workload-identity)

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

| Goal                                                                                 | `secret_providers` | `workload_identity_configs` | `environment_variables` |
| ------------------------------------------------------------------------------------ | ------------------ | --------------------------- | ----------------------- |
| Use existing static credentials in environment variables (no provider edits)         | `read`             | —                           | `manage`                |
| Create, edit, or delete static credentials                                           | `manage`           | —                           | `manage`                |
| Use existing Workload Identity-backed credentials in env vars                        | `read`             | —                           | `manage`                |
| Create, edit, or delete Workload Identity configs (and credentials referencing them) | `manage`           | `manage`                    | `manage`                |

<Note>
  **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.
</Note>

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

   {/* SCREENSHOT: Roles list page with "Create Role" button visible → /images/secrets-manager/usage/07-amp-roles-list.png */}

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.

   {/* SCREENSHOT: Role editor showing environment_variables toggles → /images/secrets-manager/usage/09-amp-role-editor-env-vars-toggles.png */}

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.

  <Note>
    **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`).
  </Note>

Click **Create** to save the variable.

<Tip>
  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.
</Tip>

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

| Credential path                                                    | When the secret is read                                                  | What rotation requires                                       |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------ |
| **Static credentials** (AWS access keys, GCP service account JSON) | At **deploy time** — value is baked into the deployment image            | Re-deploy the automation after rotating the secret           |
| **Workload Identity** (OIDC federation, AWS or GCP)                | At **every automation kickoff** — value is fetched fresh from your cloud | Nothing — the next kickoff after rotation sees the new value |

<Note>
  **If you need rotation-aware secrets** (no re-deploy on rotation), use the Workload Identity path: [AWS WI](/en/enterprise/features/secrets-manager/aws-workload-identity) or [GCP WI](/en/enterprise/features/secrets-manager/gcp-workload-identity). The trade-off is more setup effort up front (registering CrewAI Platform as an OIDC provider in your cloud) but simpler operations long-term.
</Note>

If the deploy or run fails with an error related to your secret, check the most common causes:

| Symptom                                                                     | Likely cause                                                                                                                                                                                                                                                                               |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `no credential found`                                                       | The environment variable references a provider but no specific credential was selected, and there is no default credential set for that provider type. Either select a credential explicitly on the variable, or mark a credential as default on the **Secret Provider Credentials** page. |
| `secret not found`                                                          | Typo in the **Secret Name**, or the secret does not exist in the provider account/region the credential points to. Re-check both.                                                                                                                                                          |
| Automation runs with the old value after rotating (static-credentials path) | The previous value is baked into the deployment's container image. Re-deploy the automation to pick up the rotated value. To avoid this entirely, switch the credential to the Workload Identity path.                                                                                     |
| Automation runs with the old value after rotating (Workload Identity path)  | Confirm the env var references a WI-backed credential (not a static-keys one). With WI, the next kickoff after rotation should see the new value. If it doesn't, check that the secret was actually updated in your cloud (e.g., `aws secretsmanager get-secret-value`).                   |
| `JSON key not found`                                                        | When using `secret-name#json_key`, the underlying secret must be a valid JSON object containing that key. Verify by reading the secret directly in your provider.                                                                                                                          |

## Next Steps

* [Back to the Secrets Manager overview](/en/enterprise/features/secrets-manager/overview)
* Static credentials: [AWS](/en/enterprise/features/secrets-manager/aws) · [GCP](/en/enterprise/features/secrets-manager/gcp)
* Workload Identity (rotation-aware): [AWS](/en/enterprise/features/secrets-manager/aws-workload-identity) · [GCP](/en/enterprise/features/secrets-manager/gcp-workload-identity)