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

# Secrets

> Create and link secrets across your environments

Secrets are encrypted values injected into your environment at runtime. They are the recommended way to supply API keys and other credentials to environments.

For non-sensitive configuration, use [Environment Variables](/tutorials-environments/environment-variables) instead.

## Secret Types

There are two ways to add a secret to an environment:

1. **Direct environment secrets**
   * Created directly on a specific environment
   * Only available to that environment
2. **Linked global secrets**
   * Created once under [**Keys & Secrets**](https://app.primeintellect.ai/dashboard/tokens?tab=secrets)
   * Can be linked to one or more environments
   * Useful for credentials shared across several environments, such as judge-model keys

## Where Secrets Are Used

Secrets are injected automatically for all hosted services:

* Environment Actions
* Hosted Evaluations
* Hosted Training

You do **not** need to pass them via `--env-args`.

## Adding a Direct Secret

1. Open your environment in the [Environments Hub](https://app.primeintellect.ai/dashboard/environments)
2. Go to the **Secrets** tab
3. Click **Add Secret**
4. Set a **Name**, **Value**, and optional description

## Creating and Linking a Global Secret

### 1) Create a global secret

1. Go to [**Dashboard → Keys & Secrets**](https://app.primeintellect.ai/dashboard/tokens?tab=secrets)
2. Click **Add Secret**
3. Set a **Name**, **Value**, and optional description

### 2) Link it to an environment

1. Open your environment in the [Environments Hub](https://app.primeintellect.ai/dashboard/environments)
2. Go to the **Secrets** tab
3. Click **Link Global Secret**
4. Select the secret you want to link

Once linked, the secret is available to that environment at runtime.

## Managing via CLI

### Global secrets

```bash theme={null}
prime secret list                                   # list your global secrets
prime secret create --name MY_KEY --value sk-...    # create a global secret
prime secret update <secret-id> --value sk-new      # update value
prime secret delete <secret-id>                     # delete
```

### Environment secrets

```bash theme={null}
prime env secret list owner/my-env                          # list all secrets (direct + linked)
prime env secret create owner/my-env --name MY_KEY --value sk-...  # add a direct secret
prime env secret update owner/my-env --id <id> --value sk-new      # update a direct secret
prime env secret delete owner/my-env --id <id>             # delete a direct secret
prime env secret link <global-secret-id> owner/my-env      # link a global secret
prime env secret unlink <global-secret-id> owner/my-env    # unlink a global secret
```

## Precedence and Conflict Rules

Each environment has three types of values injected at runtime:

| Type                                                                       | Encrypted | Description                                                                       |
| -------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------- |
| [**Environment variables**](/tutorials-environments/environment-variables) | No        | Plain-text key-value pairs, configured on the **Variables** tab under **Secrets** |
| **Linked global secrets**                                                  | Yes       | Encrypted values linked from your global secrets                                  |
| **Direct environment secrets**                                             | Yes       | Encrypted values set directly on the environment                                  |

### Runtime precedence

If the same name appears in more than one place, the highest-priority value wins:

1. **Environment variables** (lowest)
2. **Linked global secrets**
3. **Direct environment secrets** (highest)

### Name validation

All three types share the same naming format:

* Must start with an uppercase letter
* Can contain uppercase letters, digits, and underscores only
* Example: `MY_API_KEY`

### Conflict checks

The platform prevents name collisions. When adding or linking a secret, it will be rejected if the name is already taken by:

* An existing direct secret
* Another linked secret
* An environment variable

## Scope and Access

* **Personal secrets** can be linked to your personal environments
* **Team secrets** can be linked to environments within the same team

## Troubleshooting

<AccordionGroup>
  <Accordion title="Secret not found when linking">
    Make sure the secret exists in the same scope (personal vs team) as the environment.
  </Accordion>

  <Accordion title="A direct secret with the name ... already exists">
    Rename or remove the existing direct secret first, then link the global secret.
  </Accordion>

  <Accordion title="An environment variable with the name ... already exists">
    Rename or remove that environment variable before adding or linking the secret.
  </Accordion>

  <Accordion title="Secret missing at runtime">
    Confirm the secret appears on the environment **Secrets** tab and that your environment code reads the correct variable name.
  </Accordion>
</AccordionGroup>