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

# 1Password Vault: Service Account Integration

> Connect 1Password to Buckle with a Service Account. Agents resolve secrets at runtime via op:// references, and credentials stay in your vault.

Connect your 1Password vault to Buckle so agents can authenticate to APIs and services using secrets stored in 1Password. Credentials are resolved at runtime using [1Password Service Accounts](https://developer.1password.com/docs/service-accounts/) and `op://` references, the same format you already use in CI/CD pipelines and `.env` files. For an overview of all supported vault integrations, see [External Vaults](/docs/vaults/overview.md).

> [!NOTE]
>
> This integration is in beta. Setup and behavior may change between releases.

## Prerequisites

* Buckle running locally or via Docker
* A [1Password Service Account](https://developer.1password.com/docs/service-accounts/get-started/) with access to the vaults containing your secrets
* The `op://` references for the secrets you want agents to use (e.g. `op://API Keys/Anthropic/credential`)

## Setup

**1. Get your Service Account token**

In 1Password, go to **Developer** > **Service Accounts** and create a new service account (or use an existing one). Grant it read access to the vaults your agents need. Copy the token. You'll paste it in the next step.

> [!TIP]
>
> Use a dedicated service account for Buckle so you can revoke access independently without affecting other integrations.

**2. Connect in the dashboard**

Open the Buckle dashboard, go to **Settings** > **Apps** > **Vaults**, and click **Connect** on the **1Password** card. Paste your Service Account token and click **Connect**.

Buckle validates the token, encrypts it (AES-256-GCM), and stores it. The plain-text token is never written to disk.

**3. Add hostname mappings**

Map each API hostname to an `op://` reference pointing to the secret in your vault:

| Hostname | op\:// reference |
| - | - |
| `api.anthropic.com` | `op://API Keys/Anthropic/credential` |
| `api.openai.com` | `op://API Keys/OpenAI/api-key` |
| `api.github.com` | `op://Dev Tokens/GitHub/token` |

You can add mappings in the dashboard or via the API:

```bash theme={null}
curl -X PUT http://localhost:10254/api/vault/onepassword/mappings \
  -H "Content-Type: application/json" \
  -d '{"hostname": "api.anthropic.com", "op_ref": "op://API Keys/Anthropic/credential"}'
```

**4. Test it**

Make a request through the gateway with your agent's access token:

```bash theme={null}
curl -x http://x:YOUR_AGENT_TOKEN@localhost:10255 https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-20250514", "max_tokens": 1, "messages": [{"role": "user", "content": "hi"}]}'
```

The gateway resolves `op://API Keys/Anthropic/credential` from 1Password and injects it as the `x-api-key` header. Your agent never sees the key.

## How credentials are resolved

When an agent makes a request and no server-stored secret matches the target host, the gateway checks for a 1Password mapping:

```
Agent ──► Gateway ──► Secret Store (check DB secrets)
                │
                │  no match, 1Password mapping exists
                ▼
          1Password (resolve op:// reference via SDK)
                │
                ▼
          Gateway ──► External Service (inject + forward)
```

1. The gateway looks up the hostname in the mapping table
2. The `op://` reference is resolved via the 1Password SDK using the stored Service Account token
3. The resolved value is injected as an HTTP header and forwarded to the service
4. Resolved values are cached in memory for 60 seconds, then discarded. They are never written to the database.

The injection rule depends on the target host:

| Host | Header | Format |
| - | - | - |
| `api.anthropic.com` | `x-api-key` | Raw value |
| All other hosts | `Authorization` | `Bearer <value>` |

## op\:// reference format

1Password `op://` references follow the pattern:

```
op://vault-name/item-name/field-name
```

For example:

* `op://API Keys/Anthropic/credential` pulls the "credential" field from the "Anthropic" item in the "API Keys" vault
* `op://Dev Tokens/GitHub/token` pulls the "token" field from the "GitHub" item in the "Dev Tokens" vault

You can find the exact reference for any field in the 1Password desktop app by right-clicking a field and selecting **Copy Secret Reference**.

> [!TIP]
>
> Use the same `op://` references you already use in your CI/CD pipelines and `.env` files. No new naming conventions to learn.

## Managing mappings

| Operation | Endpoint | Method |
| - | - | - |
| List all mappings | `/api/vault/onepassword/mappings` | `GET` |
| Add or update a mapping | `/api/vault/onepassword/mappings` | `PUT` |
| Delete a mapping | `/api/vault/onepassword/mappings/{hostname}` | `DELETE` |

## Troubleshooting

> [accordion] Connection fails with 'invalid token'
>
> Make sure you're using a Service Account token (starts with `ops_`), not a personal API token. Verify the service account hasn't been deactivated in 1Password.

> [accordion] Secret resolution returns 'not found'
>
> Check that the `op://` reference is correct: vault name, item name, and field name must match exactly (case-sensitive). Also verify the service account has read access to the vault.

> [accordion] Credentials not injected after adding a mapping
>
> Resolved values are cached for 60 seconds. If you just rotated a secret in 1Password, wait for the cache to expire or restart the gateway to force a fresh resolution.

> [accordion] macOS: 'would like to access data from other apps' dialog
>
> If you're running Buckle locally on macOS Sequoia or later, you may see a system dialog about accessing data from other apps. Grant **Full Disk Access** to your terminal application (System Settings > Privacy & Security > Full Disk Access). This is a one-time setup that persists across sessions.


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