> For the complete documentation index, see [llms.txt](https://bluebricks.co/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bluebricks.co/docs/orchestration/collections/secrets.md).

# Secrets

## Overview

Secrets let you store sensitive values like API keys, credentials, or tokens at the collection level so they can be securely injected into [blueprints](/docs/orchestration/packages/blueprints-overview.md) at runtime.

By managing secrets centrally, you make it easier to reuse blueprints securely while maintaining strict control over who can access sensitive values.

<figure><img src="/files/n8N2tBbyvaeZhK2lFoNY" alt=""><figcaption></figcaption></figure>

## How collection secrets work

* **Automatic injection**: when a blueprint references a secret key that exists in the collection, the value is injected at runtime
* **Scoped by collection**: each collection has its own isolated secret store; secrets never leak across collections
* **Hidden after save**: secret values are encrypted client-side before they leave your browser and cannot be viewed again after creation. To change a secret value in the UI, delete it and create a new one.
* **Access-controlled**: only users with the right permissions can create or delete secrets. Others can reference them but not view their values.

{% hint style="info" %}
Secret values are encrypted before they leave your browser and are never stored or displayed in plain text. They are only available at runtime within the secure execution context.
{% endhint %}

## How to use secrets in blueprints

### Creating a secret

1. Navigate to the desired collection page
2. Select **Secrets** from the left side menu
3. Click **+ Add secret**
4. Enter the secret name (key) and value
5. Click **Save**

Once saved, the value is encrypted and hidden. You cannot view it again.

{% hint style="warning" %}
Secret names cannot contain hyphens (`-`) when created through the UI. Use underscores or camelCase instead (e.g., `max_password_age`).
{% endhint %}

### Referencing secrets in bricks.json

In your blueprint's `bricks.json`, reference a secret using the `Secrets` keyword followed by the secret's key.

<details>

<summary>Example bricks.json referencing a secret</summary>

```json
{
  "name": "@bluebricks/aws_iam_policy",
  "version": "1.0.0",
  "packages": {
    "iam_password_policy": {
      "name": "terraform_aws_iam_account_policy",
      "version": "1.0.3",
      "props": {
        "max_password_age": {
          "value": "Secrets.max_password_age"
        },
        "minimum_password_length": {
          "value": 14
        }
      }
    }
  }
}
```

</details>

The `max_password_age` property pulls its value from the collection's `max_password_age` secret during runtime. The platform provides the collection's secrets to the runner at deployment time, and the runner resolves each `Secrets.<key>` reference and securely injects the values into the infrastructure execution.

### Referencing secrets in bricks.yaml

In `bricks.yaml`, use the lowercase `secrets` keyword:

```yaml
packages:
  - name: terraform_aws_iam_account_policy
    version: 1.0.3
    props:
      max_password_age: secrets.max_password_age
      minimum_password_length: 14
```

For the full syntax reference, see [Inputs and Outputs](/docs/orchestration/packages/inputs-and-outputs.md#syntax-quick-reference).

To delete a secret, click the three-dot menu on the secret row and select **Delete**.

## Managed encryption keys

Bluebricks supports two options for secrets encryption:

1. **Bluebricks Managed Key**: encryption key generated and managed by Bluebricks. Contact support to enable this option.
2. **Bring Your Own Key**: use your own cloud KMS key for encryption. Supported providers:
   * **AWS KMS**: `arn:aws:kms:<region>:<account>:key/<key-id>`
   * **Azure Key Vault**: `https://<vault-name>.vault.azure.net/keys/<key-name>`
   * **GCP Cloud KMS**: `projects/<project>/locations/<location>/keyRings/<ring>/cryptoKeys/<key>`