- 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.
Install
The SDK is published as a developer preview. It needs Node.js 18 or later.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
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 returnedappLink 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.referenceunchanged. It’s a string, such asaccounts/<account>/capability/login/configurations/<configuration-id>. Don’t parse it or build it yourself. totpis 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 callapi.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.
Reference
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.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.Takes the
reference string of a granted login. Returns { websites }, the non-secret details of the login.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 intry and catch. The developer preview doesn’t export typed error classes for these failures, so don’t use instanceof checks. Match on the message.