Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 33 additions & 12 deletions vaults/1password.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ tell your users that KERNEL is the browser provider that fills their logins
through the 1Password extension, and that neither KERNEL nor your agent handles
the login values. then:

1. create a `credential_account` item to link the user's 1Password account. see [connect a 1Password account](#connect-a-1password-account).
1. create a `credential_account` item to link the user's 1Password account, and present its connect link alongside the authorization url so users with or without 1Password can connect. see [connect a 1Password account](#connect-a-1password-account).
2. create a `credential` item with `account` set to that item's key to describe the login you need. see [define a login request](#define-a-login-request).
3. invoke `1pw_create_access_request`, give the user the approval link, and poll `1pw_access_request_status`. neither needs a browser. see [request access and hand off approval](#request-access-and-hand-off-approval).
4. once the user approves, create a vault-attached browser and invoke `1pw_fill` on that item. see [fill and submit](#fill-and-submit).
Expand Down Expand Up @@ -128,7 +128,7 @@ sequenceDiagram
alt KERNEL-managed connection
App->>K: upsert credential_account
K-->>App: 1password_oauth action
App->>U: present oauth url
App->>U: present connect link and oauth url
U->>OP: consent
OP-->>U: redirect to KERNEL callback
U->>K: authorization code
Expand Down Expand Up @@ -178,7 +178,7 @@ if (account.type !== "credential_account") {
throw new Error("unexpected item type");
}
if (account.action?.name === "1password_oauth") {
// Present account.action.url to the signed-in user in your application.
// Present account.action.connect_url and account.action.url to the signed-in user.
}

account = await kernel.vaults.items.retrieve("1password-account", {
Expand All @@ -203,7 +203,7 @@ account = kernel.vaults.items.upsert(
if account.type != "credential_account":
raise RuntimeError("unexpected item type")
if account.action is not None and account.action.name == "1password_oauth":
pass # Present account.action.url to the signed-in user in your application.
pass # Present account.action.connect_url and account.action.url to the signed-in user.

account = kernel.vaults.items.retrieve("1password-account", id_or_name=vault.id, wait=60)
if account.type != "credential_account" or account.state.status != "connected":
Expand All @@ -218,25 +218,46 @@ connection secrets.

| `state.status` | meaning | next step |
| --- | --- | --- |
| `pending_authorization` | waiting for consent | present `action.url`; read with `wait` |
| `pending_authorization` | waiting for consent | present `action.url`, and `action.connect_url` when it's included; read with `wait` |
| `connected` | the connection is usable | define credential items |
| `declined` | the user declined consent | repeat the upsert to get a new authorization url, or use `1pw_recover` when it's advertised |
| `reconnect_required` | the connection needs reauthorization; `state.status_reason` explains why | repeat the upsert, or use `1pw_recover` when it's advertised |
| `revoking` | the account was disconnected or deleted, and 1Password hasn't confirmed yet. new fills are refused. | wait; KERNEL finishes it in the background. don't upsert the account until it leaves `revoking` |

the authorization url expires after a short time. repeating the same upsert
returns the current url while it's valid and issues a new one after it
expires. a `wait` read keeps holding while the status is
`reconnect_required`, so check the status instead of waiting for it to change.
the authorization url and connect link expire together after a short time.
repeating the same upsert returns the current links while they're valid and
issues new ones after they expire. a `wait` read keeps holding while the
status is `reconnect_required`, so check the status instead of waiting for it
to change.

#### Offer a connect link

the `action` also includes `connect_url`, a 1Password
[connect link](https://www.1password.dev/agentic-autofill/partners/connect-links)
for the same authorization. unlike `action.url`, it works for users who don't
have 1Password yet:

- in 1Password for iOS or Android 8.12.42 or later, it opens the app, where the user approves the connection.
- anywhere else, it opens 1Password in the browser, where a user without 1Password can sign up. if the account is still `pending_authorization` after they sign up, they connect with `action.url`.

offer `action.url` next to it, such as an "I already have 1Password" option, for
users who already use 1Password on a computer. on a phone, open `connect_url`
with the system url handler so it can reach the 1Password app; in a web view it
shows the web page instead. don't fetch, prefetch, or preview it: 1Password only
starts a sign-up for a top-level page load.

whichever link the user approves or declines first settles the authorization,
and the other stops working. 1Password lists connect links as a partner preview,
so details may change.

#### Recover a failed account link

if linking the account fails in a way KERNEL can recover from, the
`credential_account` advertises `1pw_recover` and `state.status_reason`
describes the failure. invoke it to get a new `1password_oauth` action, and
present its `url` to the user as you did when connecting. after recovery
completes, start a new authorization on the same item by repeating the account
upsert. don't delete the account to recover, and don't retry recovery
present its `url` to the user. a recovery link has no `connect_url`. after
recovery completes, start a new authorization on the same item by repeating the
account upsert. don't delete the account to recover, and don't retry recovery
automatically.

#### Disconnect an account
Expand Down
Loading