Prerequisites
- A Browserbase account, API key, and project ID.
- Node.js and an application backend with a production HTTPS OAuth callback.
- Two separate 1Password accounts on
1password.com:
Save test logins in Personal for Individual accounts or Private for Families. Business accounts don’t get the user consent screen, and 1Password doesn’t offer shared-vault logins.
Register a production OAuth client
An owner, administrator, or member of the Security group must create the client in your company’s Business account.1
Open OAuth Application
Open Integrations > OAuth Application in your Business account.If the option is missing, ask your 1Password contact to enable it using an owner or administrator’s email address.
2
Add your application's name and icon
Enter the display name and upload a PNG, JPEG, or GIF icon up to 1 MB. Both appear on the consent screen and approval prompt.You can’t add an icon after creation. Register a new client if an existing client has no icon.
3
Configure the OAuth client
1Password rejects localhost and custom URL schemes.
4
Generate and store credentials
Generate credentials and save the client ID and client secret in your backend secret store. 1Password shows the secret once.
Connect a user
Implement the authorization code flow with PKCE behind your application’s Connect 1Password button.1
Start authorization
Send the user to 1Password’s authorization endpoint with these scopes, separated by a space:
brokered-credentials:request-accessbrokered-credentials:read
state and PKCE verifier for each attempt. Use code_challenge_method=S256 and keep the verifier on your backend.For testing, use a private browser window and sign in to the personal account.2
Capture the callback
Validate
state, then read the callback values:Read the fragment in browser code and securely persist the key through your authenticated backend. Then clear the fragment with
history.replaceState.Store the key before exchanging the code. Browsers don’t send fragments to your server automatically, and 1Password delivers the key only once per connection.3
Exchange the code
On your backend, set the Keep the client secret on your backend. Don’t also send
OP_OAUTH_* variables to your registered client credentials, callback values, and PKCE verifier. Exchange the code with HTTP Basic authentication only:cURL
client_id in the form body.4
Store and refresh tokens
Store the tokens and integration key together, bound to the same user and connection.
Refresh at the same token endpoint using
grant_type=refresh_token, the current refresh_token, and both scopes.Reconnects and missing integration keys
Reconnects and missing integration keys
A reconnect can omit
integration_key while the connection is active. Keep your stored key, verify it belongs to the same user and account, and never overwrite it with an empty value.If the key is lost, revoke the connection and connect again. See Store keys and tokens.Upload the 1Password extension
Upload the extension once, then reuse its Browserbase upload ID for new sessions.1
Install dependencies
2
Package and upload the extension
Create a ZIP with Run the script to print the upload ID:
manifest.json at the root, following Browser extensions.Set BROWSERBASE_API_KEY in your environment and save this as upload-extension.mjs:Node.js: upload-extension.mjs
3
Configure your backend
The example discovers the 1Password service worker from its manifest. No separate Chrome extension ID is needed.
Network allowlist
Network allowlist
If your browser uses an outbound allowlist, permit these hosts:
api.1password.comcrl.1passwordservices.commy.1password.com
Request, approve, and fill a login
The example creates a Browserbase session, calls the extension over CDP, and verifies the website’s destination after filling. Calls run in the extension service worker, whereglobalThis.api is available.
Configure the sign-in function
Save the complete example below asagentic-autofill.mjs. Call its signIn function from your backend with these arguments:
Keep the client secret and refresh token on your backend. Deliver approval links through your authenticated application, outside model context and logs.
Try the public demo login
Try the public demo login
Save the public login shown on this test website in your personal vault, then use:
Follow the approval flow
1
Request the logins
Describe the task and the websites it needs. Each access request supports one to five logins.1Password returns an access request, entry IDs, and an approval link. See Create an access request for field limits.
2
Get the user's approval
Open the approval link on the computer running the 1Password desktop app, signed in to the connected personal account. The prompt closes after two minutes.Start checking status when the user opens the link. Use one checker per request and stop on every final state.
3
Fill and verify the login
Match the granted login by
entryId, then pass its reference unchanged to fillCredential.The example checks the destination’s origin and path against successUrl after the fill returns. Add further task actions after verification, before cleanup.Approval polling schedule
Approval polling schedule
On
rateLimitExceeded, wait at least one minute before checking again.If the request remains pending, wait for the user to say they’ve approved, then check once more. Create a new request only if it is still pending. Keep the request ID and entry IDs to support this continuation.Users can skip requested entries or add other logins, so match grants by entryId rather than array position. See Get the user’s approval.Complete Node.js example: agentic-autofill.mjs
Complete Node.js example: agentic-autofill.mjs
Node.js: agentic-autofill.mjs
Expected output
After approval, a successful fill, and navigation tosuccessUrl:
fill_submitted: The extension filled and submitted the form, then removed the filled values before returning.Website login verified: The destination’s origin and path matchsuccessUrl. The example throws if the page isn’t reached within 15 seconds.
Multi-page sign-in
Multi-page sign-in
Fill the same granted reference on each username, password, or one-time-password page before verifying the final destination. Pause page reads during every fill.
Troubleshooting
See the extension API and troubleshooting reference. Share error codes without tokens, keys, or approval links.
Zero data retention (ZDR)
The example disables session recording and logging when it creates the Browserbase session:
Read the ZDR guide for the full scope. Downloads, uploads, contexts, and extensions are separate artifacts; use Bring Your Own Storage to store them in your own AWS account.
Configure retention for your application’s logs and model provider separately.