diff --git a/vaults/1password.mdx b/vaults/1password.mdx index e0168d92..d8be288d 100644 --- a/vaults/1password.mdx +++ b/vaults/1password.mdx @@ -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). @@ -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 @@ -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", { @@ -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": @@ -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