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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bluebricks.co/docs/orchestration/collections/secrets.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.