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

   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:

   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:

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.

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

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.

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.

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.

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.