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

# 1Password Vault: Service Account Integration

> Connect 1Password to OneCLI using Service Accounts. AI agents resolve secrets at runtime via op:// references. Credentials never leave your vault until the moment they're needed.

Connect your 1Password vault to OneCLI 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](/vaults/overview).

<Note>
  This integration is in beta. Setup and behavior may change between releases.
</Note>

## Prerequisites

* OneCLI 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

<Steps>
  <Step title="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 OneCLI so you can revoke access independently without affecting other integrations.
    </Tip>
  </Step>

  <Step title="Connect in the dashboard">
    Open the OneCLI dashboard > **Secrets** page > **1Password** card. Paste your Service Account token and click **Connect**.

    OneCLI validates the token, encrypts it (AES-256-GCM), and stores it. The plain-text token is never written to disk.
  </Step>

  <Step title="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"}'
    ```
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

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

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="macOS: 'would like to access data from other apps' dialog">
    If you're running OneCLI 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.
  </Accordion>
</AccordionGroup>