Skip to main content

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.

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 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.
This integration is in beta. Setup and behavior may change between releases.

​
Prerequisites

  • OneCLI running locally or via Docker
  • A 1Password Service Account 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.
Use a dedicated service account for OneCLI so you can revoke access independently without affecting other integrations.
2

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

Add hostname mappings

Map each API hostname to an op:// reference pointing to the secret in your vault:
Hostnameop:// reference
api.anthropic.comop://API Keys/Anthropic/credential
api.openai.comop://API Keys/OpenAI/api-key
api.github.comop://Dev Tokens/GitHub/token
You can add mappings in the dashboard or via the API:
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:
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:
HostHeaderFormat
api.anthropic.comx-api-keyRaw value
All other hostsAuthorizationBearer <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.
Use the same op:// references you already use in your CI/CD pipelines and .env files. No new naming conventions to learn.

​
Managing mappings

OperationEndpointMethod
List all mappings/api/vault/onepassword/mappingsGET
Add or update a mapping/api/vault/onepassword/mappingsPUT
Delete a mapping/api/vault/onepassword/mappings/{hostname}DELETE

​
Troubleshooting

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