A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The 1Password API is how an app or AI agent works with a team's vaults: listing the vaults it can reach, reading and creating items such as logins and API credentials, updating or deleting them, and downloading files attached to an item. Access is granted through a Connect server access token sent as a bearer token, and each token is scoped to specific vaults at a read or write level, so an agent reaches only the vaults that token was issued for. The Connect API does not push events; a separate Events API returns sign-in attempts, item usage, and audit events for review.
How an app or AI agent connects to 1Password determines what it can reach. The Connect API serves the vaults and items behind a self-hosted Connect server, while the Events API and the SCIM bridge are separate connection methods with their own purpose and their own token.
The Connect REST API serves vaults, items, and item files from a self-hosted Connect server, answering by default on port 8080 under the /v1 path. It is the route an app or AI agent uses to read or store secrets, governed by a Connect server access token scoped to specific vaults.
The Events API is read-only reporting, returning sign-in attempts, item usage in shared vaults, and account audit events. Each endpoint is a POST that pulls recent events on a schedule, behind a bearer token whose feature decides which event type it can read. It is the audit stream, since the Connect API does not push events.
The SCIM bridge connects an identity provider such as Okta or Microsoft Entra ID to 1Password to automate provisioning: creating, confirming, and suspending users and managing group access. It is a separate self-hosted service with its own bearer token, not a way to read or write vault items.
1Password ships a first-party MCP server, in beta, for 1Password Environments with OpenAI Codex. It lets an agent create environments and list variable names while the secret values stay in 1Password and are injected at runtime, so the agent never sees them. It is not a route to the Connect API's vault and item endpoints.
A Connect server access token authenticates every Connect API call, sent as a bearer token. It is issued against a deployed Connect server and scoped to specific vaults, each at a read or write level, so it reaches only the vaults it was granted. It cannot be used to mint another token.
An Events API bearer token authenticates calls to the Events API and is scoped by feature, where signinattempts, itemusages, and auditevents each gate a different event type. It reads reporting data only and has no access to vault items.
The Connect API is split into areas an agent can act on, mainly the vaults it can reach, the items inside them, and the files attached to those items. Each area carries the read or write level that the calling token holds on that specific vault.
List the vaults the token can reach and read a single vault's details and metadata.
List, read, create, replace, patch, and delete the items inside a vault, including logins, passwords, and API credentials.
List the files attached to an item, read a file's details, and download its content.
List the API requests that have been made to this Connect server.
Check that the server is alive, read its state and its dependencies, and read its Prometheus metrics.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
VaultsList the vaults the token can reach and read a single vault's details and metadata.2 | ||||||
| GET | /v1/vaults | List all vaults the token can reach, with name and identifier. | read | vault: read | Current | |
Returns only the vaults the token was scoped for. A filter parameter matches a vault by name using SCIM eq syntax. Acts onvault Permission (capability) vault: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/vaults/{vaultUuid} | Get a single vault's details and metadata. | read | vault: read | Current | |
Needs read access to that vault. Acts onvault Permission (capability) vault: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ItemsList, read, create, replace, patch, and delete the items inside a vault, including logins, passwords, and API credentials.6 | ||||||
| GET | /v1/vaults/{vaultUuid}/items | List all items inside a vault. | read | vault: read | Current | |
Returns item overviews without field secrets. A filter parameter matches an item by title using SCIM eq syntax. Acts onitem Permission (capability) vault: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/vaults/{vaultUuid}/items | Create a new item in a vault. | write | vault: write | Current | |
Needs write access to that vault. The body sets the item category, such as LOGIN, PASSWORD, or API_CREDENTIAL, and its fields. Acts onitem Permission (capability) vault: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/vaults/{vaultUuid}/items/{itemUuid} | Get the full details of an item, including its field values. | read | vault: read | Current | |
This is the call that returns the secret field values, so read access to the vault exposes its secrets. Acts onitem Permission (capability) vault: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/vaults/{vaultUuid}/items/{itemUuid} | Replace an item with a new full version. | write | vault: write | Current | |
Needs write access. PUT replaces the whole item, so any field not sent is dropped. Acts onitem Permission (capability) vault: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v1/vaults/{vaultUuid}/items/{itemUuid} | Change part of an item by applying a JSON Patch (RFC 6902) document of add, remove, or replace operations. | write | vault: write | Current | |
Needs write access. Changes only the fields named in the patch, leaving the rest of the item intact. Acts onitem Permission (capability) vault: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/vaults/{vaultUuid}/items/{itemUuid} | Delete an item from a vault. | write | vault: write | Current | |
Needs write access. Removes the item and its secrets. Acts onitem Permission (capability) vault: writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Item filesList the files attached to an item, read a file's details, and download its content.3 | ||||||
| GET | /v1/vaults/{vaultUuid}/items/{itemUuid}/files | List the files attached to an item. | read | vault: read | Current | |
Needs read access to the vault holding the item. Acts onfile Permission (capability) vault: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/vaults/{vaultUuid}/items/{itemUuid}/files/{fileUuid} | Get the details of a single file attached to an item. | read | vault: read | Current | |
Returns file metadata. An inline_content parameter can include the content up to a default of about 100KB. Acts onfile Permission (capability) vault: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/vaults/{vaultUuid}/items/{itemUuid}/files/{fileUuid}/content | Download the content of a file attached to an item. | read | vault: read | Current | |
File content can hold secret material such as private keys or certificates. Requesting content over the inline size limit returns 413. Acts onfile Permission (capability) vault: readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ActivityList the API requests that have been made to this Connect server.1 | ||||||
| GET | /v1/activity | List the API requests that have been made to this Connect server. | read | — | Current | |
Pages through limit and offset parameters, where limit defaults to 50 and offset to 0. Acts onapi request Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Health & metricsCheck that the server is alive, read its state and its dependencies, and read its Prometheus metrics.3 | ||||||
| GET | /heartbeat | Ping the server for liveness. | read | — | Current | |
Liveness check, returned without vault data. Served outside the /v1 path. Acts onserver Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /health | Get the state of the server and its dependencies. | read | — | Current | |
Reports server and dependency state. Served outside the /v1 path. Acts onserver Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /metrics | Read the server's exposed Prometheus metrics. | read | — | Current | |
Operational metrics in Prometheus format. Served outside the /v1 path. Acts onserver Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
The Connect API does not push events. The separate Events API is the audit stream: it returns sign-in attempts, item usage in shared vaults, and account audit events, pulled on a schedule rather than delivered to a receiver URL.
| Event | What it signals | Triggered by |
|---|
The Connect server runs inside a team's own infrastructure and answers locally, so 1Password publishes no per-request rate limit for it. The sync that keeps it current, and the separate Events API, do have their own limits.
The Connect server runs inside a team's own network and answers requests from a local cache, so 1Password publishes no fixed per-request rate limit for the Connect API itself. The background sync that keeps the cache current talks to 1Password.com and is subject to that service's limits, and the separate Events API has its own documented rate limits. Practical throughput therefore depends on how the server is deployed and how often it must reach back to 1Password.com.
The activity endpoint pages through the limit and offset query parameters, where limit defaults to 50 and offset defaults to 0. The vault and item list endpoints return the full collection and instead support a filter parameter using SCIM eq syntax, to match a vault by name or an item by title.
Requests and responses are JSON. File content is returned from a dedicated content endpoint; a file can be requested inline up to a default of about 100KB, and larger files are downloaded from the content endpoint instead. A request for content that exceeds the size limit returns 413.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request body is invalid, such as a malformed item on a create or update, or an invalid JSON Patch document on a PATCH. | Correct the body against the item schema and resend. |
| 401 | Unauthorized | The Connect token is missing, malformed, or invalid. | Send a valid token in the Authorization Bearer header. |
| 403 | Forbidden | The token is valid but not scoped for this vault or this action, such as writing to a vault it only has read access to. | Issue or use a token with the right vault and the right read or write level. |
| 404 | Not Found | The vault, item, or file does not exist, or the token has no access to it. | Check the vault, item, and file identifiers, and confirm the token is scoped for that vault. |
| 413 | Payload Too Large | File content was requested inline but exceeds the inline size limit, around 100KB by default. | Download the file from the content endpoint instead of requesting it inline. |
The Connect API is served under a single path version, v1, and ships through dated releases of the Connect server itself rather than a dated API version. The reference is generated from a published specification that carries its own version number.
The Connect API is served under a single path version, v1, with no dated API version. It is delivered by the Connect server, which a team runs in its own infrastructure, and new fields, item categories, and fixes arrive through dated releases of that server rather than a new API version. The reference is generated from a published OpenAPI specification, version 1.7.1 at the last check.
Connect server release 1.8.1, which prevents concurrent sync of the same file across connect-sync instances. The Connect server is what serves the v1 API inside a team's infrastructure, so server releases, not API versions, carry its changes. Released on 12 September 2025.
Connect server release 1.8.0, adding multi-file reference support and improved error handling for unsynced files. Released on 9 September 2025.
An integration calls the stable v1 path; new fields and item types arrive through Connect server releases.
1Password Connect changelog ↗Bollard AI sits between a team's AI agents and 1Password. Grant each agent exactly the access it needs, read or write, vault by vault, and every call is checked and logged.