PaperClipAI/doc/connections/1PASSWORD.md

1Password

Connect from Connectors → 1Password, choose who can use the connection, and fill Paste your 1Password Service Account token. Setup links directly to Create a service account. No desktop sign-in, CLI installation, Connect server, or OAuth application is required. Change agent access and action policies on Permissions after setup.

Provider contract

Reviewed on 2026-10-22 against the official service-account guide, SDK documentation, and item-management guide. The implementation pins the official @1password/sdk to 0.5.0. 1Password's documentation MCP server searches documentation; it is not an authenticated vault integration. This connector uses a provider-owned SDK bridge through the existing rest_api connection path, rather than advertising an unsupported remote MCP URL.

Create a service account with access only to the vaults the selected agents need. Grant Read Items and Write Items for reading and managing items. An existing read-only token can connect; provider permissions still deny its writes. Vault access and permissions are immutable: create a replacement service account and reconnect in Paperclip to change them. Built-in Personal, Private, Employee, and default Shared vaults cannot be selected. Creating a service account requires a 1Password subscription and the appropriate account permissions.

The method is 1password/service-account. Its configured URL https://my.1password.com/ is a routing identity, not a public REST or MCP endpoint. The SDK uses the account address in the token and handles regional API access. Paperclip accepts only HTTPS account addresses under 1password.com, 1password.ca, or 1password.eu, without custom ports, paths, or URL credentials. There are no OAuth metadata, registration, callback, refresh, or revocation endpoints in this method. Reconnect replaces the token through the normal vault credential writer; provider revocation is managed in 1Password.

Actions and governance

Action	Risk	Result
onepassword_list_vaults	Read	Vaults authorized by the service account
onepassword_list_items	Read	Item summaries in one vault
onepassword_get_item	Read	An item including its secret fields
onepassword_resolve_secret	Read	The value of one op://vault/item/field reference
onepassword_create_item	Write	A new Login, Password, API Credentials, or Secure Note item
onepassword_update_item	Write	An item with specified properties updated
onepassword_archive_item	Destructive	An archived item
onepassword_delete_item	Destructive	A deleted item

Updates preserve the SDK's item version and omitted properties. Supplied fields and tags arrays replace their previous arrays. Supported editable field types are Text, Concealed, Totp, Url, and Email. Vault and item operations require IDs; secret references support the provider's ordinary op:// format. Vault administration, sharing, document/file exports, and arbitrary commands are not exposed. 1Password enforces the service account's vault boundary on every call.

All actions use existing company, agent, responsible-user, connection-grant, profile, Allowed / Ask first / Off, quarantine, and audit checks. Setup uses the existing default of all discovered actions Allowed for the chosen agents. The credential field explicitly describes required vault permissions. Select trusted agents: item reads and secret-reference resolution intentionally return secret values to the agent and ordinary tool-result history. The service-account token itself is always redacted, including if it is stored in an item being read.

Personal setup creates user-owned secrets and declarations; shared setup creates company-owned secrets. Credentials never enter connection configuration or agent environment variables. The worker receives only the selected invocation token and validated arguments. It has no inherited environment or desktop identity.

Each invocation starts a disposable worker to isolate SDK initialization and cryptography from the API event loop. There is no background polling or retained SDK client. The worker is terminated on completion or deadline (15 seconds for discovery, at most 30 seconds for calls). Termination stops local work; an already accepted provider mutation can finish remotely. Writes are never retried automatically. Provider errors use fixed actionable messages, and worker output is bounded to 1 MiB; raw SDK errors and stdout/stderr never enter server logs.

Verification

server/src/services/connectors/onepassword/onepassword.test.ts exercises strict arguments, patch preservation, forged endpoint rejection, and actual worker deadline termination with unrelated event-loop progress. server/src/services/connectors/onepassword/worker.test.ts executes the worker entry point with synthetic SDK results to verify nested token redaction and oversized-result rejection before posting a result to the gateway. server/src/__tests__/onepassword-connection.test.ts exercises encrypted credential ownership, personal declarations, reads and writes through a running agent's gateway session, classification, refresh, reconnect, action policy, cross-company denial, and revocation of a retained session. The ordinary suite uses provider fixtures. PAPERCLIP_ONEPASSWORD_LIVE=1 plus an environment-supplied OP_SERVICE_ACCOUNT_TOKEN enables the account-bound variant, which creates and deletes only synthetic test items. Never put a token in a command argument.

Setup and management use the production components; the 1Password Storybook stories provide catalog, token, rejection, inline task setup, narrow-screen, and Permissions/Test simulations. These fixtures do not establish provider access.

Live qualification status is recorded in tool-method-permission-reviews.json.

On 2026-10-22, the supplied account passed live connect, eight-action discovery, vault listing through a running agent's gateway, catalog refresh, token replacement/reconnect preserving the connection ID, another gateway read, removal, and denial through the retained gateway session. Audit and connection responses did not contain the credential. The account could list one vault but 1Password denied a minimal synthetic item creation for lack of permission; no item was created.

On 2026-10-23, a replacement token with Write Items permission passed the live governed lifecycle for both personal and shared credentials. All eight actions ran through an actual run-scoped gateway: list vaults, create and list a synthetic item, read it, update it and verify the update, resolve its secret reference, archive it, and delete it. Catalog refresh, reconnect, another read, connection removal, and retained-session denial also passed. Both synthetic items were deleted, and their absence from item listings was verified. Audit, responses, and the captured log did not contain the credential.

The first 2026-10-23 attempt stopped before any provider call because the host had exhausted PostgreSQL semaphores. The passing run used a temporary test-only PostgreSQL profile with ten connections and fewer workers; no shared service or host limit was changed. The deterministic provider suite covers mutations and the ordinary policy boundaries separately.

The browser walkthrough used a fresh local test instance, a personal credential, and one explicitly selected disposable agent. It reached the normal Permissions screen with all eight actions. Initial setup failures during development (a canonical URL mismatch and a rewritten token label) were corrected before the passing walkthrough. An inherited Node --input-type flag also broke the first compiled-worker smoke; workers now start with an explicit empty Node argument list, and packaging is verified separately from source execution.

Branding provenance

Official source: 1Password's product site, retrieved 2026-10-22:

• Light theme: https://1password.com/favicon/icon-v2.svg
• Dark theme: https://1password.com/favicon/icon-v2-light.svg

The native icon shapes and colors are preserved. Each SVG adds only an explicit matching viewBox so the official icon scales inside Paperclip's standard gray frame. The browser-served manifest contains asset paths only.

Shared changes

1Password owns its schemas, SDK mapping, account-address validation, errors, worker lifecycle, and result sanitization under server/src/services/connectors/onepassword/. The existing native-provider catalog registry registers its probe, tools, classification, contract hashes, and executor. Shared setup, health, discovery, and gateway code dispatch that existing contract; existing providers retain their behavior. No schema or database migration is needed. The shared credential-label formatter preserves explicit "Paste your" prompts from the manifest, so setup shows Paste your 1Password Service Account token without a provider-specific UI branch. Ordinary key labels keep their existing presentation.