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

# Vaults and Secrets

> Store credentials in vaults, share them with factories, and expose them to factory work items as environment variables: vault scopes, attachment precedence, secret kinds, write-only values, and per-task vault restrictions.

Beta

> [!NOTE]
>
> **Factory** is in private preview. The feature is enabled per workspace by
> the **Orq.ai** team and the vaults API is not part of the public SDKs, the
> CLI or the API reference yet.

A **Vault** is a named collection of **Secrets**. Factories attach vaults, and every work item that runs in the factory receives the secrets of its attached vaults as environment variables. Vaults keep credentials such as registry tokens, test database URLs or third-party API keys out of repositories and prompts, and let several factories reuse the same values.

## Vault scopes

A vault has exactly one scope, chosen at creation and immutable afterwards:

| Scope | Owner | Who can attach it | Managed from |
| - | - | - | - |
| **Factory** | One factory | Only that factory | **Factory** > **Settings** > **Secrets** |
| **Workspace** | The workspace | All factories, or the factories selected in the vault's sharing | **Settings** > **Vaults** |

Workspace vaults are created and shared by workspace Admins. Factory vaults are managed by anyone with access to the factory. A vault outside the reach of the current user is not listed.

## Attach vaults to a factory

Open **Factory** > **Settings** > **Secrets** and attach a vault from the list of vaults the factory may use: its own vaults plus the workspace vaults shared with it. The **Effective secrets** table shows the resulting environment of a work item: one row per variable name with the vault that supplies it.

Attachment order is the precedence order. When two attached vaults define the same name, the first attached vault wins and the others are listed as shadowed. Reorder the attachments to change which vault wins.

A vault cannot be deleted, and a factory cannot be removed from a workspace vault's sharing, while that factory still has the vault attached. Detach it first.

## Secrets

Each secret in a vault has:

| Field | Description |
| - | - |
| **Name** | The environment variable name: uppercase letters, digits and underscores, starting with a letter or underscore. Unique within the vault and immutable. Names starting with `ORQ_` are reserved for platform credentials. |
| **Kind** | `Variable`: plain configuration, visible in output. `Secret`: redacted from run output and transcripts. `Setup secret`: available only while the computer blueprint is built, removed before the agent starts. |
| **Value** | Write-only. It is stored encrypted with the workspace key and never returned by the UI or the API. Enter a new value to rotate it. |
| **Description** | Optional note shown next to the secret. |

Rotating a value reaches running work items on their next credential refresh.

## Restrict a task to specific vaults

By default a task's work items receive every vault attached to the factory. When creating or editing a task, restrict it to a subset of the attached vaults, or to none, when the work must not see a credential.

## Limitations

| Limitation | Impact | Workaround |
| - | - | - |
| Values are never displayed | A forgotten value cannot be recovered from **Orq.ai** | Rotate the secret with a new value |
| Secrets are environment variables only | No file, cookie or OIDC style credentials | Write the file from the variable in the blueprint |
| Personal secrets are not supported | Every user of the factory receives the same values | Use a factory vault per team or factory |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.