canonical: https://jentic.com/apis/1password.local/1password-connect

# 1Password Connect

1Password Connect is a self-hosted REST API that lets applications and infrastructure read and write items stored in 1Password vaults without exposing master credentials. The server runs alongside your workloads, exchanges a Connect bearer token (JWT) for scoped vault access, and exposes endpoints for vaults, items, files, activity logs, and health probes. It is the deployment path teams use to inject secrets into CI/CD pipelines, Kubernetes clusters, and homelab services without reaching out to the public 1Password.com API. The catalogued spec covers 15 endpoints across Items, Vaults, and Activity, plus heartbeat, health, and Prometheus metrics endpoints for operational monitoring.

## For AI agents

Read, write, and manage secrets stored in self-hosted 1Password vaults via a local Connect server. Agents can fetch credentials, create or patch items, and pull file attachments using a scoped Connect bearer token.

## Scope

Does not handle 1Password.com tenant administration, sign-in event streaming, or end-user app sync - use for self-hosted vault item and file access only.

## Capabilities

- Retrieve a specific secret item from a vault by UUID for use in a deployment or runtime call
- Create a new login, password, or API credential item inside a designated vault
- Patch individual fields on an existing item (rotate a password, update a tag) without overwriting the whole record
- Download the content of a file attached to a vault item, such as a TLS certificate or signing key
- List API request activity to audit which Connect token accessed which vault and when
- Probe Connect server health and Prometheus metrics to confirm the secrets backend is live before requesting credentials

## Use cases

### Inject Secrets Into CI/CD Pipelines

Pipelines often need database passwords, signing keys, and third-party API tokens at build or deploy time. A self-hosted 1Password Connect server lets a CI runner exchange a Connect bearer token for the specific item it needs and nothing else, so secrets never live in pipeline variables or repository files. The catalogued endpoints under /vaults/{vaultUuid}/items support reading individual items by UUID, which fits the typical CI pattern of resolving a known credential just before it is used. Setup typically takes a few hours once the Connect server is running.

Example prompt: Call GET /vaults/{vaultUuid}/items/{itemUuid} to fetch the production database password item from the designated vault and return only the password field value.

### Provide Runtime Secrets To Kubernetes Workloads

Workloads running in clusters need short-lived access to credentials such as object storage keys, service account tokens, and webhook signing secrets. 1Password Connect runs as a sidecar or in-cluster service so pods can request items by vault and item UUID over the local network rather than reaching out to the public internet. Combining /vaults/{vaultUuid}/items reads with the heartbeat endpoint allows workloads to fail fast when the secrets backend is unhealthy. Initial integration with the official Kubernetes operator usually completes within a day.

Example prompt: Probe GET /heartbeat, then call GET /vaults/{vaultUuid}/items?filter=title eq "s3-backup-key" to locate the storage credential item before mounting it into the pod environment.

### Audit Secret Access For Compliance

Compliance reviews require a record of which token accessed which secret and when. The /activity endpoint on Connect returns a paginated log of API requests handled by the server, which can be exported into a SIEM or compared against expected access patterns. Combined with item update endpoints, teams can correlate credential rotations against the activity feed. Building a basic audit export takes a few hours once a Connect token with appropriate scope is provisioned.

Example prompt: Call GET /activity with a since parameter covering the last 24 hours and filter the results for any read events against the production-keys vault.

### Rotate And Patch Stored Credentials

Credential rotation usually only needs to overwrite the password or token field while leaving notes, tags, and section ordering intact. The PATCH /vaults/{vaultUuid}/items/{itemUuid} endpoint accepts a JSON Patch document, so an automation can update a single field without resending the entire item body. This pattern keeps an audit-friendly diff in 1Password and avoids accidental overwrites of metadata maintained by humans. Wiring this into an existing rotation runner typically takes under a day.

Example prompt: Send PATCH /vaults/{vaultUuid}/items/{itemUuid} with a JSON Patch operation that replaces the value of the password field with a freshly generated 32-character secret.

### AI Agent Secret Retrieval Through Jentic

Agents that orchestrate deployments, run security checks, or operate internal tools regularly need scoped access to secrets without holding long-lived credentials in their context. Through Jentic, an agent searches for a 1Password Connect operation by intent, loads its input schema, and executes the call with the Connect bearer token kept in your Jentic One instance. Raw tokens never enter the model context, and the agent only ever sees the resolved item value it asked for. End-to-end wiring of search, load, and execute takes under an hour.

Example prompt: Use Jentic to search for "fetch a secret from 1Password Connect", load the GET /vaults/{vaultUuid}/items/{itemUuid} schema, and execute it for the database-credentials item.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /vaults | List all vaults available to the Connect token |
| GET | /vaults/{vaultUuid}/items | List items inside a specific vault |
| GET | /vaults/{vaultUuid}/items/{itemUuid} | Read the full details of a single item |
| POST | /vaults/{vaultUuid}/items | Create a new item in a vault |
| PATCH | /vaults/{vaultUuid}/items/{itemUuid} | Patch a subset of fields on an existing item |
| GET | /vaults/{vaultUuid}/items/{itemUuid}/files/{fileUuid}/content | Download raw file content attached to an item |
| GET | /activity | Retrieve API request activity for auditing |
| GET | /heartbeat | Probe Connect server liveness |

## Key resources

- **Vaults** — List vaults available to the Connect token and read individual vault metadata by UUID.
- **Items** — Create, read, fully update, partially patch, and delete items inside a vault, including logins, passwords, API credentials, and secure notes.
- **Files** — List files attached to an item, fetch file metadata, and download raw file content such as certificates or signing keys.
- **Activity** — Retrieve a paginated log of API requests handled by the Connect server for audit and compliance reporting.
- **Server Health** — Check liveness via the heartbeat endpoint, dependency state via the health endpoint, and operational metrics via the Prometheus metrics endpoint.

## Why Jentic

- **Setup:** Wiring 1Password Connect by hand means managing its Connect bearer token and pointing at your self-hosted Connect server host yourself. Through Jentic you install once, import 1Password Connect from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Connect puts the vault id in the URL path (/vaults/{vaultUuid}/items/...), so a rule can pin your agent to one vault: it can read that vault's items and files and nothing else. You choose the operations it may call, so item creation or updates are not included unless you add them.
- **Credential handling:** Your 1Password Connect bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'fetch a secret from 1Password Connect' or 'list items in a vault', and Jentic returns the matching Connect operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **1Password Events** — Streams sign-in attempts, item usage, and audit events from the 1Password.com tenant - pairs with Connect for end-to-end secrets observability.
- **Akeyless Vault** — SaaS-first secrets management platform with dynamic secrets and zero-knowledge encryption - alternative to running self-hosted 1Password Connect.
- **HashiCorp Nomad** — Workload orchestrator that consumes secrets from external stores at job dispatch time - commonly paired with a self-hosted secrets API like 1Password Connect.

## FAQ

### What authentication does the 1Password Connect API use?

Connect uses an HTTP bearer scheme with a Connect token issued in JWT format and sent in the Authorization header on every request. The token is scoped to a specific set of vaults that you grant access to when issuing it. Through Jentic, the Connect token is stored in your Jentic One instance and never enters the agent's context - agents receive only the resolved item value they requested.

### Can I rotate just a single field on an item with the 1Password Connect API?

Yes. PATCH /vaults/{vaultUuid}/items/{itemUuid} accepts a JSON Patch document so you can replace the password or token field without resending the rest of the item. PUT /vaults/{vaultUuid}/items/{itemUuid} is also available when you need to overwrite an item in full.

### What are the rate limits for the 1Password Connect API?

Connect runs as a self-hosted server inside your own infrastructure, so request throughput is bounded by the resources allocated to the Connect container rather than by a vendor-imposed quota. The /metrics endpoint exposes Prometheus counters and latencies you can use to set your own alerting thresholds, and the /health endpoint reports the state of dependencies before a burst of reads.

### How do I retrieve a secret from a vault through Jentic?

Search Jentic for "fetch a secret from 1Password Connect", load the schema for GET /vaults/{vaultUuid}/items/{itemUuid}, then execute it with the vault and item UUIDs. The Jentic Python SDK pattern is asynchronous: pip install jentic, then await client.search, client.load, and client.execute. The Connect bearer token stays in your Jentic One instance.

### Can the 1Password Connect API download files attached to items?

Yes. GET /vaults/{vaultUuid}/items/{itemUuid}/files lists files attached to an item, and GET /vaults/{vaultUuid}/items/{itemUuid}/files/{fileUuid}/content returns the raw file bytes. This is the path teams use to pull TLS certificates, SSH keys, or signing material into a workload at runtime.

### Is the 1Password Connect API free to use?

The Connect server software is distributed by 1Password and runs in your own infrastructure, but it requires a 1Password Business or Teams plan to issue Connect tokens and host the underlying vaults. There is no per-call charge from 1Password for Connect requests.

### How do I check that the 1Password Connect server is reachable before requesting a secret?

Call GET /heartbeat for a fast liveness probe and GET /health for a deeper check that reports the state of the server and its dependencies. Workloads commonly chain a heartbeat call before a sensitive item read so they fail fast if the secrets backend is offline.

### Can I limit what my agent is allowed to do with the 1Password Connect API?

Yes. Jentic One runs self-hosted, so your own rules decide which 1Password Connect operations and credentials the agent may use. Because Connect puts the vault id in the URL path (/vaults/{vaultUuid}/items/...), a rule can pin the agent to a single vault so it reads only that vault's items and files. You also choose the exact operations it may call, so write actions like POST /vaults/{vaultUuid}/items or PATCH /vaults/{vaultUuid}/items/{itemUuid} stay off limits unless you add them.