From e4f5004b1f10ee773d39468931f35adf88938d91 Mon Sep 17 00:00:00 2001 From: Behroz Saadat Date: Thu, 19 Nov 2026 12:14:10 -0500 Subject: [PATCH 1/3] Document 1Password connect links Co-Authored-By: Claude Opus 5.5 --- vaults/1password.mdx | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/vaults/1password.mdx b/vaults/1password.mdx index e0168d92..f3d1bebc 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 offer its connect link to users who don't have 1Password yet. 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). @@ -218,7 +218,7 @@ 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`; 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 | @@ -229,6 +229,25 @@ 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. +#### 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. use it to reach users who don't have 1Password yet: + +- in 1Password for iOS or Android 8.12.42 or later, it opens the app and connects the account there. +- anywhere else, it starts sign-up for a new 1Password account. after signing up, the user connects with `action.url`. + +because the browser path always starts a new account, show `connect_url` as +the main option and `action.url` as "I already have 1Password". open the link +as a page load in the user's browser or with the system url handler, not in a +web view: 1Password only starts sign-up for a top-level page load, and the +1Password app only opens links handed to it by the system. + +whichever link the user answers first settles the authorization, and the other +stops working. both expire together, and repeating the upsert returns fresh +ones. a recovery link has no `connect_url`. + #### Recover a failed account link if linking the account fails in a way KERNEL can recover from, the From 71336658d9946e0ed79f0afa4432e1f2ac357e46 Mon Sep 17 00:00:00 2001 From: Behroz Saadat Date: Thu, 19 Nov 2026 12:26:02 -0500 Subject: [PATCH 2/3] Describe the connect link's browser path without promising sign-up Also fixes the expiry and web view details against 1Password's spec. Co-Authored-By: Claude Opus 5.5 --- vaults/1password.mdx | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/vaults/1password.mdx b/vaults/1password.mdx index f3d1bebc..bc0e9f7a 100644 --- a/vaults/1password.mdx +++ b/vaults/1password.mdx @@ -218,7 +218,7 @@ connection secrets. | `state.status` | meaning | next step | | --- | --- | --- | -| `pending_authorization` | waiting for consent | present `action.url` and `action.connect_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 | @@ -233,20 +233,21 @@ expires. a `wait` read keeps holding while the status is the `action` also includes `connect_url`, a 1Password [connect link](https://www.1password.dev/agentic-autofill/partners/connect-links) -for the same authorization. use it to reach users who don't have 1Password yet: +for the same authorization. unlike `action.url`, it also works for users who +don't have 1Password yet: -- in 1Password for iOS or Android 8.12.42 or later, it opens the app and connects the account there. -- anywhere else, it starts sign-up for a new 1Password account. after signing up, the user connects with `action.url`. +- 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`. -because the browser path always starts a new account, show `connect_url` as -the main option and `action.url` as "I already have 1Password". open the link -as a page load in the user's browser or with the system url handler, not in a -web view: 1Password only starts sign-up for a top-level page load, and the -1Password app only opens links handed to it by the system. +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 answers first settles the authorization, and the other -stops working. both expire together, and repeating the upsert returns fresh -ones. a recovery link has no `connect_url`. +whichever link the user approves or declines first settles the authorization, +and the other stops working. both links expire at the same time. a recovery link +has no `connect_url`. #### Recover a failed account link From 0c5eeee96df916062814d5bb4a52dca0fed18a02 Mon Sep 17 00:00:00 2001 From: Behroz Saadat Date: Thu, 19 Nov 2026 18:06:03 -0500 Subject: [PATCH 3/3] Address review: present both links in the checklist, samples and diagram Co-Authored-By: Claude Opus 5.5 --- vaults/1password.mdx | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/vaults/1password.mdx b/vaults/1password.mdx index bc0e9f7a..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, and offer its connect link to users who don't have 1Password yet. 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": @@ -224,17 +224,18 @@ connection secrets. | `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 also works for users who -don't have 1Password yet: +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`. @@ -246,17 +247,17 @@ 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. both links expire at the same time. a recovery link -has no `connect_url`. +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