Skip to main content
Partner preview
Agentic Autofill integrations are built on the browser extension. If your product needs the SDK, contact 1Password for guidance before you build with it, so we can review our shared security model with you. With the SDK, your code can receive credential values, which changes what your platform is responsible for.
The 1Password JavaScript SDK lets your code create access requests and check their status without a browser. It can also read a granted login’s username, password, and one-time password. Use the SDK in two ways:
  • Request with the SDK, fill with the extension. Your code asks for access before a browser or tab exists, and the extension fills when the agent reaches the sign-in page. Your code never receives a value.
  • Read with the SDK. Your code receives the values. Your application becomes responsible for handling them safely and for how they’re used, including filling them into a page.
The extension and the SDK work together:

Install

The SDK is published as a developer preview. It needs Node.js 18 or later.
The developer preview has no backwards-compatibility guarantees. Pin the exact version, and expect changes before general availability.

Create a client

Every call takes two credentials: the person’s current access token, and the integration key from their connection. See Connect a user.
  • The client exposes only client.credentialBroker. The items, vaults, and secrets APIs belong to other client types and aren’t available with OAuth credentials.
  • The client is bound to the access token you passed in. Access tokens expire after 15 minutes. When you refresh, create a new client.
  • The client sends every request to the API host named in the integration key, so a key issued on 1password.com talks to api.1password.com. There’s no host setting. If your network restricts outbound traffic, allow that host.

Create an access request

The fields and limits are the same as the extension’s. See Create an access request. You need accessRequest.id to check status, each accessRequest.entries[].id to match grants to entries, and appLink to send the person to approval.

Send the person to approval

Deliver the returned appLink to the person’s device, the same way you would with the extension. Use it exactly as returned. Treat it as opaque: don’t parse it, change it, or build it yourself, because its format can change.

Wait for the decision

getStatus returns the current status immediately. It doesn’t wait for the person to decide, so your code decides when to check again, under the same rules as with the extension. Wait for the decision explains them in full:
  • Check only while the state is pending, and never after a final state.
  • Start when the person opens the approval link. Don’t check a request they haven’t opened.
  • Follow the schedule: nothing for the first 5 seconds, then every 2 seconds until 30 seconds, every 5 seconds until 1 minute, every 10 seconds until 2 minutes, and optionally every 20 seconds until 3 minutes. Then stop, ask the person to tell you when they’ve approved, and check once more.
getStatus takes the request id, not its path. resolved, denied, failed, and expired are final. Each arrives as a normal return value, not an exception, with resolved empty for every state except resolved. expired isn’t returned yet: 1Password is adding it for requests nobody decides on, so handle it now, and treat any state you don’t recognize as final. If your loop stops with the request still pending, the request isn’t failed, and stopping doesn’t change or cancel it. Ask the person to tell you when they’ve approved, then check once more.

Read a granted login

  • Pass granted.reference unchanged. It’s a string, such as accounts/<account>/capability/login/configurations/<configuration-id>. Don’t parse it or build it yourself.
  • totp is the current one-time password, computed when you read.
  • Every read is a fresh call to 1Password. Read again when you need the value, rather than caching it. After the grant ends, the next read fails instead of returning a stale value.
  • Keep values out of logs, prompts, and model context, and discard them as soon as they’re used.

Request with the SDK and fill with the extension

Switching from the SDK to the extension doesn’t require a new request. Keep the request ID, entry IDs, and granted references, and pass them to the part of your system that drives the browser. When the agent reaches the sign-in page, wait for the extension to initialize, turn on Agentic Mode for the tab or the whole browser, then call api.agenticAutofill.v1.fillCredential with granted.reference as resourcePath. The SDK’s read methods and the extension take the same reference string. Use the same person’s access token and integration key that created and resolved the request.
This way 1Password fills and submits the login without exposing its username, password, or one-time password to your code.

Reference

Promise<OAuthClient>
Creates a client from { accessToken, integrationKey }.
Promise<AccessRequestCreateResponse>
Registers an access request. params is { goal?, entries }, with 1 to 5 entries of { type, parameters: { website }, reason?, keywords? }. Returns { accessRequest, appLink }. accessRequest is the full request: path, id, identity, state, createdAt, goal, and entries with their IDs. appLink is the onepassword:// link that opens the request for approval.
Promise<AccessRequestStatus>
Returns { state, resolved }. state is pending, resolved, denied, failed, or expired. Every state except pending is final. resolved lists { entryId?, reference } for each granted login, where reference is a string, and is empty for every other state.
Promise<LoginDetails>
Takes the reference string of a granted login. Returns { websites }, the non-secret details of the login.
Promise<LoginCredential>
Takes the reference string of a granted login. Returns { username?, password?, totp? } for the login.

Errors

The SDK rejects its promises on failure, so wrap calls in try and catch. The developer preview doesn’t export typed error classes for these failures, so don’t use instanceof checks. Match on the message.