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

# Bitwarden Secrets Manager

> Store your integration credentials in Bitwarden Secrets Manager and reference them in Tierity using {{bw.secret_name}} — without ever exposing raw secrets inside Tierity.

## Overview

Tierity integrates with [Bitwarden Secrets Manager](https://bitwarden.com/products/secrets-manager/) so your team can store sensitive credentials — API tokens, passwords, private keys — in Bitwarden's vault and reference them inside Tierity using a simple template syntax:

```
{{bw.my_secret_name}}
```

Anywhere Tierity accepts credentials (integration config fields, API request headers, environment variables for scripts), you can use a `{{bw.*}}` reference instead of pasting a raw secret. Tierity resolves the value at runtime by calling the Bitwarden Secrets Manager API.

**Why this matters:**

* Secrets never live in Tierity's database — only the reference does
* Revoke the machine account token in Bitwarden and Tierity immediately loses access to all secrets
* Rotate individual secrets in Bitwarden without reconfiguring anything in Tierity
* Audit secret access in Bitwarden's event log

## Prerequisites

* A [Bitwarden](https://bitwarden.com) account with **Secrets Manager** enabled (Teams or Enterprise plan)
* Permission to create machine accounts and projects in your Bitwarden organization
* Manage access (or higher) in Tierity to configure the integration

## Concepts

> **Secrets Manager vs Password Manager**
>
> Bitwarden offers two products. This integration uses **Secrets Manager** — the developer-focused secrets API designed for machine-to-machine access. It is separate from the Password Manager vault your team uses for logins.

> **Machine accounts**
>
> A machine account is a non-human Bitwarden identity that holds an access token. You create one specifically for Tierity, grant it access to the secrets Tierity needs, and give the token to Tierity. Revoking the machine account immediately cuts off Tierity's access.

> **Projects**
>
> In Bitwarden Secrets Manager, secrets are organized into projects. You can give Tierity access to a dedicated project (e.g., `tierity-integrations`) so it can only read the secrets you explicitly put there — not everything in your org.

## Setup

**1. Enable Secrets Manager in Bitwarden**

If you haven't already, enable Secrets Manager for your Bitwarden organization:

1. Log in to the [Bitwarden web app](https://vault.bitwarden.com).
2. Go to your **Organization → Settings → Subscription**.
3. Enable **Secrets Manager**.

**2. Create a project for Tierity secrets**

1. In the Bitwarden web app, switch to **Secrets Manager** (toggle in the left sidebar).
2. Go to **Projects → New Project**.
3. Name it something clear, like `tierity-integrations`.
4. Click **Save**.

> [!TIP]
>
> Using a dedicated project gives Tierity access to only the secrets you put in it — nothing else in your Bitwarden organization.

**3. Add your secrets to the project**

For each credential you want to use in Tierity, create a secret in the project:

1. Go to **Secrets → New Secret**.
2. Set a **Name** — this is the key you'll use in `{{bw.name}}` references. Use lowercase with underscores (e.g., `semgrep_api_token`, `checkmarx_api_key`).
3. Set the **Value** — the actual credential.
4. Assign it to your `tierity-integrations` project.
5. Click **Save**.

Repeat for each secret you want accessible from Tierity.

> [!NOTE]
>
> Secret names are case-sensitive in `{{bw.*}}` references. `{{bw.Semgrep_Token}}` and `{{bw.semgrep_token}}` resolve to different secrets.

**4. Create a machine account for Tierity**

1. In Secrets Manager, go to **Machine Accounts → New Machine Account**.
2. Name it `tierity` (or `tierity-<your-env>` if you run multiple environments).
3. Click **Save**.
4. On the machine account page, go to **Access Tokens → Generate Token**.
5. Give the token a name and set an expiry (or leave it non-expiring — your choice).
6. Copy the token value. **This is the only time it will be shown.**

> [!WARNING]
>
> Store the token somewhere safe immediately. If you lose it, you'll need to generate a new one.

**5. Grant the machine account access to your project**

1. Go to **Projects → tierity-integrations → Access**.
2. Click **Grant Access**.
3. Select your `tierity` machine account.
4. Set the permission to **Read** (Tierity only needs to read secrets, not create or modify them).
5. Click **Save**.

**6. Connect Bitwarden to Tierity**

1. In Tierity, go to **Config → Integrations → Bitwarden Secrets Manager**.
2. Click **Configure**.
3. Enter the **Access Token** you generated in the previous step.
4. Click **Save & Test** to verify Tierity can authenticate and list accessible secrets.

If the test succeeds, Tierity is connected and `{{bw.*}}` references will start resolving.

## Using `{{bw.*}}` references

Once connected, you can use `{{bw.secret_name}}` anywhere Tierity accepts a credential or configuration value.

### In integration settings

When configuring an integration (e.g., Semgrep, Checkmarx, Snyk), instead of pasting an API token directly into the field, enter a Bitwarden reference:

```
{{bw.semgrep_api_token}}
```

Tierity resolves this to the secret value at runtime when it needs to make an API call. The raw token is never stored in Tierity's database.

### In API request headers

When building API requests in the **API Testing** module, use `{{bw.*}}` references in headers, query parameters, or request bodies:

```http theme={null}
Authorization: Bearer {{bw.target_api_key}}
X-API-Key: {{bw.internal_service_token}}
```

### In script templates and packet templates

Reference secrets in community scripts and packet templates to avoid hardcoding credentials in shared scripts:

```bash theme={null}
curl -H "Authorization: Bearer {{bw.burp_api_token}}" https://...
```

## How secret resolution works

When Tierity encounters a `{{bw.secret_name}}` reference, it:

1. Calls the Bitwarden Secrets Manager API using the stored machine account token.
2. Looks up the secret by name within the projects the machine account has access to.
3. Substitutes the resolved value in-memory for that request.
4. The resolved value is **never logged or persisted** — only the `{{bw.secret_name}}` reference is stored.

If a secret cannot be resolved (name doesn't exist, token revoked, network error), Tierity returns an error rather than sending the request with an unresolved placeholder.

## Revoking access

To immediately cut off Tierity's access to all Bitwarden secrets:

1. In Bitwarden Secrets Manager, go to **Machine Accounts → tierity**.
2. Click on the access token.
3. Click **Revoke**.

All `{{bw.*}}` references in Tierity will stop resolving until you provide a new token.

To rotate the token without downtime:

1. Generate a new token on the same machine account.
2. Update the token in **Tierity → Config → Integrations → Bitwarden**.
3. Revoke the old token.

## Disconnecting

To remove the Bitwarden integration from Tierity:

1. Go to **Config → Integrations → Bitwarden Secrets Manager**.
2. Click **Disconnect**.

Tierity will stop resolving `{{bw.*}}` references. Any integration fields or API requests using references will fail until you either reconnect or replace the references with raw values.

> [!NOTE]
>
> Disconnecting does not delete secrets from your Bitwarden vault. It only removes the token from Tierity.


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