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

# Secret references

> Point settings at a secret in 1Password, Bitwarden or AWS Secrets Manager instead of pasting it in. Tierity fetches it at the moment it's used.

## Overview

Anywhere Tierity asks for a credential, such as an integration's API key, you can enter a **reference** to a secret instead of the secret itself. Tierity stores the reference and fetches the real value from your vault each time it's needed. Rotate the secret in your vault and Tierity picks up the new value; it's never copied into Tierity's database.

## Syntax

```
sec://<scope>/<vault>/<path>[#field]
```

| Part | Values |
| - | - |
| **scope** | `org` for your organization's vaults, `me` for your personal ones |
| **vault** | `op` (1Password), `bw` (Bitwarden Secrets Manager), `ssm` (AWS Secrets Manager), `tierity` (secrets stored in Tierity) |
| **path** | The item or secret name. For 1Password you can include the vault: `Infra/Prod DB`. Encode spaces as `%20`. |
| **field** | Optional. A field of the item, or a key in a JSON secret. |

Examples:

```
sec://org/op/Infra/Prod%20DB#password     org 1Password: vault "Infra", item "Prod DB", field "password"
sec://org/bw/okta-api-token                org Bitwarden secret "okta-api-token"
sec://org/ssm/prod/db#password             org AWS Secrets Manager: secret "prod/db", JSON key "password"
sec://me/tierity/github-pat                your personal secret stored in Tierity
```

A reference can be the whole value, or sit inside a longer one as `${sec://…}`:

```
Bearer ${sec://org/op/Monitoring/Webhook#token}
```

In inputs that accept references, type `sec://` to get suggestions.

## Org and personal scopes

Organization settings and personal settings never share secrets:

* **Organization settings** (integration configs, workflow rules, notification channels) can only use `sec://org/…`. They're used by background jobs and by every member, so a personal secret there would leak to everyone. Tierity rejects a `sec://me/` reference in an organization setting.
* **Your own settings** (your personal connections and tokens) can use both `sec://me/…` and `sec://org/…`.
* **Runs you start yourself**, such as an API request, can use both.

## Setting up vaults

* **Organization vaults:** connect [1Password](https://docs.tierity.com/integrations/1password.md) or [Bitwarden Secrets Manager](https://docs.tierity.com/integrations/bitwarden.md) under **Config → Integrations**, or AWS Secrets Manager through the [AWS integration](https://docs.tierity.com/integrations/aws.md).
* **Personal vaults and secrets:** go to **Profile → Secrets** to connect your own vault or store a personal secret in Tierity. Personal secrets are encrypted at rest.

## Legacy syntax

The older `{{op.name}}`, `{{bw.name}}` and `{{ssm.name}}` forms still work and always refer to the organization's vaults.


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