@lunch-money/developer-docs 2.11.2-preview.4 → 2.11.2-preview.6

package/docs/oauth/authorization-code.md

@@ -42,7 +42,7 @@ On your server, generate:
 
 Redirect the browser to the discovered authorization endpoint with `response_type=code`, your `client_id`, exact `redirect_uri`, `state`, `code_challenge`, and `code_challenge_method=S256`.
 
-Lunch Money handles sign-in, budgeting-account selection, and consent. A user may have multiple budgeting accounts, but this authorization is for the one they select. Keep the authorization attempt bound to the application user who started it.
+Lunch Money handles sign-in, budgeting-account selection, and consent. It may reuse an existing browser login session, and the person may be able to continue with a different Lunch Money user from the authorization screen. A user may have multiple budgeting accounts, but this authorization is for the one they select. Keep the authorization attempt bound to the authenticated application user who started it; do not assume which Lunch Money user will complete it.
 
 > [!NOTE] Scopes come from the client registration
 > You do not need to send `scope`. If your OAuth library includes it, Lunch Money ignores the requested value and uses the client's complete registered scope set. An authorization request cannot narrow or expand that set; changing scopes requires a replacement client.
@@ -63,9 +63,9 @@ Treat `access_denied` as a normal user decision. Do not log the callback query s
 
 Send a form-encoded request to the discovered token endpoint with `grant_type=authorization_code`, the code, exact `redirect_uri`, and original `code_verifier`. A confidential client authenticates with HTTP Basic using its client ID and secret. Do this server-side.
 
-Store `access_token`, `token_type`, granted `scope`, and expiration metadata securely. If a `refresh_token` is returned, keep it server-side as a high-value credential.
+Keep the returned credentials in temporary server-side state while you identify the authorization. Do not make an unidentified credential set available to the application or commit it to the normal connection store yet. If a `refresh_token` is returned, treat it as a high-value credential even during this temporary step.
 
-## 4. Call the API
+## 4. Identify and store the connection
 
 Send the access token in the header:
 
@@ -77,13 +77,17 @@ Authorization: Bearer YOUR_ACCESS_TOKEN
 
 The operation must be allowed by the token's scope and by the user's access to the selected budgeting account. See the [scope catalog](/oauth/scopes).
 
-`GET /v2/me` requires `me:read`. Its `id` identifies the Lunch Money user, while `account_id` and `budget_name` identify the selected budgeting account. Associate these details with the application user's connection and display the connected budget. When reconnecting, use the new response to establish the account identity rather than assuming the user selected the same budget. See [users, budgeting accounts, and access tokens](/oauth/concepts#users-budgeting-accounts-and-access-tokens).
+Call `GET /v2/me` immediately after the token exchange, before normal credential persistence. It requires `me:read`. Strictly validate the response: `id` identifies the Lunch Money user, `account_id` identifies the selected budgeting account, and `budget_name` is its display name. When reconnecting, use this response to establish the account identity rather than assuming the user selected the same budget. See [users, budgeting accounts, and access tokens](/oauth/concepts#users-budgeting-accounts-and-access-tokens).
 
-Store the credential set under the authenticated application user's ID and the returned `account_id`. Treat that pair as the owner of the connection: update the same record when the user reauthorizes that budgeting account, and create or select a separate record when they authorize another account. Persist the access token, refresh token when present, scope, expiration metadata, and account identity together. Do not use `budget_name` as the key or try to derive the account identity by parsing the opaque access token.
+Store the credential set under the authenticated application user's ID and the returned Lunch Money user `id` and `account_id`. Those three fields establish the owner and provider identity for the connection, even if your database also assigns an internal connection ID for routing. Atomically create a complete record when that combination is new, or replace the complete credential set when the same application user reauthorizes the same Lunch Money user and budgeting-account pair. Persist the access token, refresh token when present, scope, expiration metadata, Lunch Money user `id`, `account_id`, and `budget_name` together, then make that Lunch Money identity and connection active. Do not use `budget_name` as a key or try to derive identity by parsing the opaque access token.
 
-Retain the returned Lunch Money user `id` with the connection as well. Your application establishes ownership through its own authenticated session. When authorization starts, store the authenticated application user's internal ID in the server-side authorization attempt associated with `state`. After validating the callback and calling `GET /v2/me`, store the credentials with that application-user ID and the returned Lunch Money `id`/`account_id` pair.
+If `GET /v2/me` fails validation or the complete record cannot be persisted, discard the temporary credentials and leave existing connections unchanged. A successful token exchange alone must not create an unidentified or partially saved connection.
 
-For later requests, look up the selected connection using both its connection ID and the authenticated application user's internal ID. If no matching record exists, reject the request before loading or decrypting credentials. When the same application user reauthorizes a budgeting account, replace credentials only in the record matching that application user and Lunch Money `id`/`account_id` pair. Values supplied by the browser, including a connection ID or `account_id`, select a candidate record but do not establish ownership. See [Associate credentials with your application user](/oauth/security#associate-credentials-with-your-application-user) for the storage and ownership rules.
+Your application establishes ownership through its own authenticated session. When authorization starts, store the authenticated application user's internal ID in the server-side authorization attempt associated with `state`. After validating the callback and calling `GET /v2/me`, store the credentials with that application-user ID and the returned Lunch Money `id`/`account_id` pair.
+
+For later requests, look up the selected connection using both its internal connection ID and the authenticated application user's internal ID. Then verify that its stored Lunch Money user `id` and `account_id` belong to the active identity before loading or decrypting credentials. Values supplied by the browser select only a candidate record; they do not establish ownership or provider identity.
+
+When reauthorization completes, replace credentials only in the record matching the authenticated application user and the returned Lunch Money `id`/`account_id` pair. A different Lunch Money user authorizing the same shared `account_id` must create or update a separate owned connection. After an identity change, hide the previous Lunch Money user's connections and clear or partition displayed profile, configuration, and cached financial data. See [Associate credentials with your application user](/oauth/security#associate-credentials-with-your-application-user) for the storage and ownership rules.
 
 ## 5. Continue or recover
 

package/docs/oauth/concepts.md

@@ -18,7 +18,7 @@ During OAuth authorization, the user selects one budgeting account and approves
 
 For example, Alex can access both “Household” and “API testing.” If Alex selects “API testing” during authorization, your application's access token operates on that budgeting account. It cannot use the same token to read or update “Household.” Scopes determine which operations the application may perform within the selected account; they do not add access to other budgeting accounts.
 
-When applications store OAuth credentials, they should associate the authorization with the application user who started the flow and keep track of which Lunch Money user and budgeting account that connection represents.
+When applications store OAuth credentials, they should associate the authorization with the application user who started the flow and identify the connection by the Lunch Money user and budgeting account pair. Two Lunch Money users can both authorize access to the same shared budgeting account, so `account_id` alone is not a complete connection identity.
 
 ### Identify the authorized user and account
 
@@ -30,21 +30,40 @@ If your client has the `me:read` scope, call `GET /v2/me` with the access token.
 | `account_id` | The selected budgeting account's ID |
 | `budget_name` | The selected budgeting account's display name |
 
-Use the IDs to associate API data with the correct user and budgeting account, and show `budget_name` so the application user can see which budget they are using. Do not treat `id` alone as the budgeting-account identity or use `budget_name` as a unique identifier. Access tokens are opaque credentials; obtain this information from the API response rather than parsing the token.
+Use `account_id` as the stable identifier for the budgeting account and `id` as the identifier for the Lunch Money user who completed authorization. Together they identify the Lunch Money side of the connection. For an application with its own accounts, store that pair within the authenticated application user's ownership boundary. A standalone native application without its own account system uses the `id` and `account_id` pair as its local connection identity.
+
+Show `budget_name` so the application user can see which budget they are using, but do not use it as a key: two budgeting accounts can have the same name. When names collide, add a secondary label such as the account ID only where the UI needs to distinguish them. Access tokens are opaque credentials; obtain this information from the API response rather than parsing the token.
+
+### Identify the user who completed authorization
+
+Lunch Money may reuse an existing browser login session, and the authorization screen may let the person continue with a different Lunch Money user. Shared browser state therefore means that a login can be reused when available; it does not guarantee which user will complete authorization. A fresh or ephemeral browser request is also only an intent, not proof of identity.
+
+After every successful code exchange, call and strictly validate `GET /v2/me`. Treat its `id` as the Lunch Money user who actually completed authorization and its `account_id` as the selected budgeting account. Do not infer that identity from browser cookies, callback fields, `budget_name`, the user who was active before authorization, or token contents.
 
 ### Select a different budgeting account
 
-Applications should provide a UI that allows users to switch between budgeting accounts they have already authorized through that application, or to authorize another budgeting account.
+Applications that may retain more than one Lunch Money identity should show the active Lunch Money user and which saved connection is the **active budget**. Provide two distinct actions:
+
+- Select another saved connection belonging to the active Lunch Money user to switch the active budget without starting OAuth again.
+- Choose **Authorize another budget** to start OAuth and connect a budgeting account that is not yet saved.
 
 To connect to a new, previously unauthorized, budgeting account, send the user through authorization again and have them select it. Changing a locally stored account ID does not change which account an existing token can access. Refreshing a token renews access for its existing authorization; it does not select another budgeting account.
 
-Authorizing a second budgeting account creates or reuses that budget's connection and does not revoke the first one. Update each connection's credentials and account identity together, and keep cached data from one account separate from data loaded for another.
+Applications do not need a separate client-side “use another user” action. The ordinary **Authorize another budget** action starts authorization; Lunch Money handles any login reuse or user switching. After `/v2/me` identifies the result, make that Lunch Money identity active and show only its connections. Clear or partition the previously displayed profile, configuration, and cached financial data before showing the new identity.
+
+Authorizing a second budgeting account for the same Lunch Money user creates or reuses that user's connection and does not revoke the first one. Update each connection's credentials and identity together, and keep cached data from one account separate from data loaded for another.
 
 ### Reauthorize an existing budgeting account
 
-If the user selects a budgeting account that is already connected to your application, treat the authorization as a reconnection of that existing connection. Match it by the stable `account_id`, keep that connection's identity, and atomically replace its stored access-token and refresh-token set with the credentials from the successful exchange. Reauthorizing the same budgeting account reuses that account's grant family; it does not create a second connection or affect the user's other budgeting accounts.
+If authorization returns the same Lunch Money user `id` and budgeting-account `account_id` as an existing owned connection, treat it as a reconnection. Atomically replace that connection's stored access-token and refresh-token set with the credentials from the successful exchange. A different Lunch Money user authorizing the same shared `account_id` creates or updates a separate connection; it must not overwrite the first user's credentials.
+
+When the user chooses to switch between existing authorized budgets, select a saved connection only from the active Lunch Money identity and use that connection's stored access token to make API calls. All account-specific actions must use the active connection. Clear or partition cached financial data when the active connection changes so data from the previous budget is not shown under the new selection. If the active connection is removed, select a documented remaining connection for the same Lunch Money user or enter a disconnected state. Never fall back to another user's hidden connection.
+
+### Retain connections for an inactive Lunch Money user
+
+An application may retain credentials for a Lunch Money user who is not currently active when its application-user ownership model permits it. Switching identities should hide the previous user's connections and clear or partition that user's displayed data, but hiding a connection does not revoke it or delete its stored credentials. If that Lunch Money user authorizes again later, the application may make the user's retained connections visible again.
 
-When the user chooses to switch between existing authorized budgets, select the saved connection for that `account_id` and use its stored access token to make API calls. The application UI should show which budgeting account is currently active.
+An application may instead delete stored credentials as part of its own sign-out or user-switch policy. Make that policy understandable in the interface. In particular, distinguish disconnecting or remotely revoking a budgeting-account authorization from forgetting its local credential without revoking remote access.
 
 ## Client types and credentials
 

package/docs/oauth/development.md

@@ -27,26 +27,36 @@ For a client in development, register an HTTP redirect using a supported loopbac
 
 You may choose any available port, but the complete redirect URI sent during authorization must match the registered value exactly. `localhost` and `127.0.0.1` are different hosts, so register the form your application sends. Non-loopback HTTP hosts, embedded credentials, and URI fragments are not supported.
 
-The user's browser—not Lunch Money's server—connects to the loopback listener. Keep PKCE and `state` protections in place just as you would for a hosted callback. Before requesting review, also register the HTTPS callback used by the deployed application; the loopback URI can remain available for local testing.
+The user's browser—not Lunch Money's server—connects to the loopback listener. Keep PKCE and `state` protections in place just as you would for a hosted callback. Before requesting review, also register the HTTPS callback used by the deployed application; the loopback URI can remain available for local testing. After approval, you can add or keep a loopback redirect as long as that production HTTPS callback remains. See [after approval](/oauth/review-and-approval#after-approval).
 
 > [!NOTE] Test an approved client with your development team
-> After a client is approved, other team members can continue developing and testing the application's Lunch Money functionality. If the approved client has a loopback redirect registered, each developer who can run the application locally may authorize access to their own Lunch Money budgeting account. The client ID is public, but developers working on a confidential web client also need access to its client secret through your team's secure credential-management process. Do not share access tokens or refresh tokens between developers.
+> After a client is approved, other team members can continue developing and testing the application's Lunch Money functionality. You can add or keep a loopback redirect on the approved client as long as the production HTTPS callback remains. If a loopback redirect is registered, each developer who can run the application locally may authorize access to their own Lunch Money budgeting account. The client ID is public, but developers working on a confidential web client also need access to its client secret through your team's secure credential-management process. Do not share access tokens or refresh tokens between developers.
 
 ## Repeat or reset authorization
 
-During development, the client owner can run authorization again whenever they want to repeat the sign-in, budgeting-account selection, consent, and callback flow. They do not need to revoke the current token first. Selecting the same budgeting account reuses that account's grant; selecting a different account creates or reuses a separate connection and leaves the first connection available.
+During development, the client owner can run authorization again whenever they want to repeat the sign-in, budgeting-account selection, consent, and callback flow. They do not need to revoke the current token first. The authorization server may reuse the current browser login or let the person continue with a different Lunch Money user. Treat the validated `/v2/me` user/account pair—not previous browser state—as the completed authorization's identity.
 
 To test how the application responds after access is revoked, revoke the current token and make another API request with it. Lunch Money should reject the request, and the application should discard its saved credentials and begin authorization again. The [token revocation guide](/oauth/tokens#revoke-access) includes copyable `curl` requests for development testing.
 
 ## Test the complete client
 
-If the client owner has multiple budgeting accounts, test authorization with a separate test account first, then repeat the flow and select a different account. For a client registered with `me:read`, confirm that `GET /v2/me` returns the same user `id` and the newly selected `account_id`. Store the credentials under the authenticated application user and that account ID, show the selected budget, and do not display cached data from another connection. Switch back to the first saved connection without authorizing again, then verify that revoking or invalidating one connection does not affect the other.
+Test with one Lunch Money user authorizing multiple budgeting accounts, then with a second Lunch Money user authorizing through the same browser or device. For a client registered with `me:read`, strictly validate the returned `id` and `account_id` after every exchange. Store credentials under the authenticated application user and that Lunch Money user/account pair. For a standalone app without its own accounts, use the Lunch Money user/account pair as the local connection identity.
 
 1. Complete authorization. For each attempt, your application should create a random `state` value, save it with the application user's session, and verify that Lunch Money returns the same value to the callback. Rejecting a missing, changed, or reused value prevents a callback started elsewhere from being attached to the wrong session.
 2. Keep the PKCE verifier with that same authorization attempt and use it when exchanging the returned code. Confirm that an exchange with a missing or changed verifier fails; this prevents someone who intercepts the code from using it.
 3. Read the token response's `scope` field and confirm that it contains the complete scope set registered for the client. Do not inspect or parse the access token itself.
 4. Call every scope-dependent feature, including negative permission cases.
-5. Test user denial, missing or changed `state`, callback errors, and interrupted authorization attempts.
+5. Test user denial, missing or changed `state`, callback errors, and interrupted authorization attempts. Confirm that denial or a failed `/v2/me` validation leaves all existing connections unchanged.
+6. Make `GET /v2/me` fail or return an invalid shape after a successful exchange. Confirm that the application saves no unidentified or partial connection.
+7. Reauthorize an already connected Lunch Money user/account pair. Confirm that the application atomically replaces that connection's credentials, makes it active, and does not create a duplicate.
+8. Authorize as a second Lunch Money user through the same browser or device. Confirm that the previously displayed profile, configuration, saved-budget choices, and cached financial data disappear, while any retained credentials remain hidden.
+9. Return to the first Lunch Money user. Confirm that only that user's retained connections become visible again and that the other user's connections cannot be selected.
+10. Have two different Lunch Money users independently authorize the same shared `account_id`. Confirm that the application stores separate credentials keyed by Lunch Money user `id` and `account_id`, without overwriting either connection.
+11. Give two visible budgets the same `budget_name`. Confirm that they remain separate by `account_id` and that the UI disambiguates them only where needed without using the name as a key.
+12. Attempt to select a connection belonging to an inactive Lunch Money user. Confirm that the request is rejected before credentials or cached data are loaded.
+13. Switch the active budget and exercise API calls, refresh, revocation, and local deletion. Confirm that each action and every cache entry affects only the active user/account connection.
+14. Remove the active Lunch Money user's final budget. Confirm that the application enters a disconnected state rather than exposing or selecting another user's hidden connection.
+15. Test remote disconnect and local-only credential deletion separately. Confirm local-only deletion, explain that the remote authorization remains active, and keep unrelated connections unchanged.
 
 ## Test reauthorization before refresh
 

package/docs/oauth/index.md

@@ -2,7 +2,7 @@
 
 OAuth lets your application access Lunch Money on behalf of a user without asking that person to copy and share a personal access token. **If you are building an application for anyone other than yourself, use OAuth.** It gives each user a familiar Lunch Money sign-in and consent experience while keeping their personal access token out of your application.
 
-![OAuth authorization-code flow across your application, the Lunch Money user, and Lunch Money. The application redirects the user's browser, Lunch Money handles sign-in and presents the budgeting-account and permission choices, the user approves access, Lunch Money returns an authorization code, and the application exchanges it for tokens and calls the API.](/v2/images/oauth-authorization-flow.svg)
+![OAuth authorization-code flow across your application, the Lunch Money user, and Lunch Money. The application redirects the user's browser, Lunch Money handles sign-in and presents the budgeting-account and permission choices, the user approves access, Lunch Money returns an authorization code, and the application exchanges it for tokens, calls GET /v2/me, saves the identified connection, and calls the API for that account.](/v2/images/oauth-authorization-flow.svg)
 
 ## Choose OAuth or a personal access token
 

package/docs/oauth/native-apps.md

@@ -15,17 +15,29 @@ Use Lunch Money's authorization-server discovery document and configure `token_e
 
 Use a redirect mechanism that returns control to your app and that your platform can bind to it. Claimed Universal Links or Android App Links provide stronger app ownership than a custom URI scheme when correctly configured. A private-use scheme must contain a dot, such as `app.example.demo:/oauth/callback`, and must be protected against interception.
 
-Native clients may use an HTTP loopback redirect with `localhost`, `127.0.0.1`, or `[::1]`. The scheme, host, path, and query string must exactly match the registered URI, but the port may differ so the application can bind an ephemeral port at runtime. The exception applies only to loopback redirects for native clients; native HTTPS and private-use scheme redirects must match every component of the registered URI exactly.
+Native clients may use an HTTP loopback redirect with `localhost`, `127.0.0.1`, or `[::1]`. The scheme, host, path, and query string must exactly match the registered URI, but the port may differ so the application can bind an ephemeral port at runtime. The exception applies only to loopback redirects for native clients; native HTTPS and private-use scheme redirects must match every component of the registered URI exactly. The loopback hosts are not interchangeable: a client registered with `http://127.0.0.1/cb` cannot authorize with `http://localhost:4000/cb` or `http://[::1]:4000/cb`, so register the host your app actually binds to.
 
 ## Store and renew tokens
 
 Store tokens in Keychain on Apple platforms. On Android, use current Keystore-backed storage guidance from your maintained library; do not start new work with deprecated `EncryptedSharedPreferences` APIs. Coordinate refresh-token use, persist replacements, and fall back to interactive authorization after terminal failure.
 
+After every code exchange, call and strictly validate `GET /v2/me` before adding the credentials to the app's normal connection store. For an app without its own user accounts, identify each local connection by the returned Lunch Money user `id` and budgeting-account `account_id` pair. Atomically create a record for a new pair or replace the credential set for an existing pair. Two Lunch Money users may authorize the same shared `account_id`; their credentials must remain in separate records. If identification or persistence fails, discard the temporary credentials instead of saving a partial or unidentified connection. Retain `budget_name` for display, but never use it as a key because different budgets can share a name.
+
+The platform authentication browser may reuse an existing Lunch Money login, and Lunch Money may let the person use a different user from the authorization screen. An ephemeral-session request is only an intent to avoid shared browser state; it does not prove which user completed authorization. Do not infer identity from browser cookies, callback fields, budget names, or token contents. The validated `/v2/me` response is authoritative.
+
+Show the active Lunch Money identity when the app may retain more than one, show which authorized budget is active, and provide one separate **Authorize another budget** action that starts OAuth. Do not require another client-side action for switching Lunch Money users. Selecting an existing connection must not start authorization again, and the app must allow selection only among saved budgets for the active Lunch Money user.
+
+All API calls, refreshes, revocations, local deletions, and cached data must apply to the active user/account connection. Clear or partition profile, configuration, and cached financial data when the identity or budget changes. When the active connection is removed, choose a deterministic remaining connection for that Lunch Money user or enter a disconnected state; never expose another user's hidden connection as a fallback. Use a secondary label such as the account ID only when duplicate visible budget names need disambiguation.
+
+The app may retain credentials for inactive Lunch Money users in secure storage. Switching users hides the previous identity's connections without revoking or deleting them, and authorizing as that identity later may restore its saved budgets. Alternatively, an app may delete credentials during its own sign-out or user-switch lifecycle. Make the chosen behavior understandable without prescribing a particular native control.
+
+Present remote disconnect or revocation separately from forgetting a credential only on the device. Confirm local-only deletion and explain that it leaves the remote authorization active.
+
 ### Keep application users' connections separate
 
 A native app can support multiple application users on the same device. If your app has its own sign-in system, keep each user's saved Lunch Money connections in a separate storage namespace. Bind the authorization attempt to the application user who started it, and retain the Lunch Money `id` and `account_id` returned by `GET /v2/me` with each credential set. Only load a connection after verifying that it belongs to the currently authenticated application user. Secure device storage does not perform that application-level ownership check for you.
 
-On sign-out or user switching, stop work using the previous user's credentials and clear in-memory tokens, the active connection selection, and cached financial data. Remove saved credentials if your app does not retain connections across sign-ins; otherwise, make them available only after their owner signs in again. Do not attach an OAuth callback or refresh result from the previous session to the newly signed-in user.
+On application sign-out or application-user switching, stop work using the previous application user's credentials and clear in-memory tokens, the active connection selection, and cached financial data. Remove saved credentials if your app does not retain connections across sign-ins; otherwise, make them available only after their application owner signs in again. Do not attach an OAuth callback or refresh result from the previous session to the newly signed-in application user.
 
 If your app has no separate user accounts, the device's OS account and app storage protections provide the local access boundary. Anyone allowed to use the unlocked app may be able to use its saved connections; separate budgeting-account records alone do not authenticate different people.
 

package/docs/oauth/register-client.md

@@ -11,7 +11,7 @@ Before you add OAuth to your application code, register an OAuth client with Lun
 
 List the Lunch Money features your application will provide, then use the [scope catalog](/oauth/scopes) to choose the smallest complete set of permissions those features require. Select `offline_access` only if the application needs to continue making API requests after the initial access token expires and while the user is away.
 
-If your application may support more than one budgeting account for the same application user, always include `me:read`. After authorization, `GET /v2/me` lets your application record the Lunch Money user's `id` and the selected budgeting account's `account_id`, then store each connection under the correct application user and account pair. The same scope is also required when your application only needs to identify the single budgeting account it has connected.
+If your application may support more than one Lunch Money user or budgeting account, always include `me:read`. After authorization, `GET /v2/me` lets your application record both the Lunch Money user's `id` and the selected budgeting account's `account_id`, then store the connection under the complete application-owner and Lunch Money user/account identity. The same scope is also required when your application only needs to identify one connected budgeting account.
 
 Scopes cannot be changed after registration. While you are developing your application, creating a replacement client is inexpensive, so let the scope set evolve as you learn what the application needs. Aim to have the application's core functionality—and its required permissions—settled before you submit the client for review.
 
@@ -32,6 +32,8 @@ A redirect URI tells Lunch Money where to return the user after authorization. R
 
 Web applications normally use an HTTPS callback. If you need a callback for local development, review the [loopback guidance](/oauth/development#local-loopback-callbacks) before registering one. Mobile and desktop applications may use a private-use scheme containing a dot, such as `app.example.demo:/oauth/callback`, or a verified HTTPS link accepted by the Developer Portal.
 
+After the client is approved, you can add or replace redirect URIs in the Developer Portal without submitting another initial review. An approved confidential web client must keep a production HTTPS callback. See [after approval](/oauth/review-and-approval#after-approval).
+
 ## Register the OAuth client
 
 Open the [new OAuth client form](/oauth/applications/new) in the Developer Portal. Then:

package/docs/oauth/review-and-approval.md

@@ -10,7 +10,7 @@ When the application is ready, submit its client for review in the Developer Por
 | --- | --- | --- |
 | `development` | The client has not been submitted for review; only its owner can authorize it | Configure and test, then request review. |
 | `pending_review` | Review has been requested and is waiting for or receiving review; review-critical fields are frozen | Continue owner testing or cancel the request. |
-| `active` | The review was approved; other Lunch Money users may authorize the application | Operate within the approved identity and scope set. |
+| `active` | The review was approved; other Lunch Money users may authorize the application | Keep configuration current; identity updates reach users after Lunch Money reviews them. |
 | `rejected` | Changes were requested | Read feedback, revise editable configuration, and resubmit. |
 | `disabled` | Lunch Money disabled the client; its owner is notified, authorization is unavailable, and existing grants no longer work | Review the reason provided and contact developer support when appropriate. |
 
@@ -62,8 +62,12 @@ There is no review comment thread, so use the new request's additional context t
 
 ## After approval
 
-An `active` client can be authorized by other users. Reviewed identity fields, redirect configuration, and the registered scope set remain frozen after approval. Client-secret rotation and revocation remain available subject to lifecycle and security checks.
+An `active` client can be authorized by other users. Keep its configuration current in the Developer Portal. You do not need to contact Lunch Money to rename the application, move hosting, or update a support address.
 
-For an exceptional identity or configuration change, contact [developer support](mailto:developer-support@lunchmoney.app). A scope change always requires a replacement client and user reauthorization.
+Changes save immediately, and the client stays `active`. Redirect URIs, support email, description, and developer name take effect as soon as you save them. An approved confidential web client must keep at least one public HTTPS redirect.
+
+Name, logo, homepage URL, and privacy policy URL also save immediately, but Lunch Money users continue to see the last approved identity on the consent screen and Connected Apps page until Lunch Money reviews the update. The Developer Portal shows that as an identity update in review; it is not a return to `rejected`, and existing authorizations keep working.
+
+Client-secret rotation and revocation remain available subject to lifecycle and security checks. Scopes and client type cannot be changed after registration. A scope change requires a replacement client and user reauthorization.
 
 Next: [Review the security checklist](/oauth/security).

package/docs/oauth/sample-applications.md

@@ -186,6 +186,8 @@ Before adapting the code, read the repository's [OAuth code guide](https://githu
 
 The open-source sample you just ran is designed to make the Lunch Money integration code easy to find, understand, and adapt. The modules under `src/oauth` show the OAuth responsibilities that a confidential server-side application needs: discovery, authorization attempts, callback validation, credential ownership and storage, API access, optional refresh, revocation, and safe error handling.
 
+The sample represents an authenticated application user with a fixed local demo identity. After authorization, it uses the Lunch Money user `id` returned by `GET /v2/me` to choose which saved budgets are visible; credentials retained for another Lunch Money user remain hidden. A production confidential application replaces the fixed demo identity with the application user from its authenticated server-side session and identifies each owned connection by the returned Lunch Money user `id` and budgeting-account `account_id` pair.
+
 Treat these modules as a working reference, not as a package to copy unchanged into production. The in-memory implementation demonstrates serialized refresh and complete credential replacement for one `applicationUserId` and `connectionId`, but it does not provide durable encrypted storage, database transactions, distributed per-connection locking, failed-persistence recovery across restarts, multi-instance coordination, or tenant isolation. The sample keeps those application-specific decisions outside the teaching code so you can see exactly where your implementation must provide them.
 
 When refresh succeeds, the sample stores the replacement access token, refresh token, scope, and expiration metadata together without displaying token values. Your refresh-capable application must preserve that boundary, serialize refreshes for each application user and connection, and atomically store the complete rotated credential set. Retry transient failures according to your application's policy, but treat `invalid_grant` as terminal: stop refreshing, discard unusable credentials, and require reauthorization. Disconnect must invalidate the refresh token as well as the current access token so continuing access cannot resume.
@@ -210,6 +212,15 @@ the installed application performs OAuth and owns its credential. If a trusted
 server performs the code exchange and stores credentials, use the confidential
 Node.js sample above instead.
 
+Unlike the confidential sample, the native sample has no separate application
+account or server-side application-user boundary. It identifies local
+connections directly by the Lunch Money user `id` and budgeting-account
+`account_id` returned by `GET /v2/me`. It can retain connections for more than
+one Lunch Money user on the device, but only the active user's budgets are
+visible or selectable. Applications that add their own sign-in system must put
+that pair inside the authenticated application user's storage and ownership
+boundary.
+
 The native repository's [walkthrough](https://github.com/lunch-money/lm-oauth-native-expo-example/blob/main/docs/WALKTHROUGH.md) is the canonical hands-on guide;
 complete the registration, development-build, authorization, `/v2/me`,
 optional refresh, revocation, and local-reset walkthrough there.

package/docs/oauth/security.md

@@ -26,7 +26,9 @@ If your browser code uses access tokens, keep them available for no longer than
 
 A confidential application must authenticate its own user before starting Lunch Money OAuth. Bind each authorization attempt to that authenticated user's server-side session, then recover the owner from the consumed server-side attempt after the callback is verified. Do not let the callback choose who owns the resulting credentials.
 
-Store each budgeting-account connection under a stable internal application-user ID. Retain the Lunch Money user `id` and budgeting-account `account_id` returned by `GET /v2/me` alongside that connection's credential set. The application-user ID identifies who may use the saved connection; the Lunch Money IDs identify whose authorization and which budgeting account the tokens represent. Do not use an email address, callback parameter, form field, or other browser-supplied value to establish the credential owner.
+Store each budgeting-account connection under a stable internal application-user ID. Within that owner, use both the Lunch Money user `id` and budgeting-account `account_id` returned by `GET /v2/me` as the provider identity. Your database may assign a separate internal connection ID for routing and references; it does not replace the `(application user ID, Lunch Money user id, account_id)` fields used to create or update a provider connection. Do not use an email address, callback parameter, form field, browser cookie, or other browser-supplied value to establish the credential owner or provider identity.
+
+An application user may own connections for more than one Lunch Money user, although applications do not have to expose that capability. If your application supports only one Lunch Money identity per application user, detect a different `id` after `GET /v2/me` and handle it explicitly; never overwrite the existing identity's credentials.
 
 ```text
 Authenticated application user
@@ -38,11 +40,15 @@ When the user returns to your application, authenticate them through your applic
 
 For example, if Alex and Sam both use your application, Sam must not be able to use Alex's saved credentials by submitting Alex's connection ID. This remains true even if they both have access to the same Lunch Money budgeting account. Each application user must authorize their own connection. If Alex has authorized two budgeting accounts, both connections belong to Alex's application user and may be listed and selected within Alex's authenticated session. Each connection still uses the credential set for its own Lunch Money `id`/`account_id` pair.
 
-Enforce this ownership check for every API request, refresh, reauthorization, revocation, and deletion involving a saved connection. Background jobs must carry the connection's stored owner and identity so they use the same checks without an interactive session. Updating credentials after reauthorization must remain within the original application user's connections and preserve the Lunch Money `id`/`account_id` identity. A different identity must not silently overwrite an existing connection.
+Enforce this ownership and identity check for every API request, refresh, reauthorization, revocation, and deletion involving a saved connection. Background jobs must carry the connection's stored owner and identity so they use the same checks without an interactive session. Updating credentials after reauthorization must remain within the original application user's connections and match both the returned Lunch Money `id` and `account_id`. A different Lunch Money user authorizing the same shared account must not silently overwrite an existing connection.
 
 Durable credentials must be encrypted at rest, and backend access should be limited to the services and operators that need it. Encryption protects stored secrets; your application must still enforce ownership when it reads or uses them. Never return refresh tokens or client secrets to browser JavaScript. List connections using non-secret metadata such as `budget_name`, and keep their credentials in the protected store.
 
-Disconnecting one budgeting account should revoke continuing access for that connection and remove its locally stored credentials. Keep the user's other connections intact. On application sign-out or user switching, clear session-specific connection selections and cached data so the next user cannot use the previous user's connection. Signing out of your application and disconnecting Lunch Money are distinct actions; retained connections must remain accessible only through their owner's authenticated session or authorized background jobs.
+Apply API calls, refresh, revocation, local deletion, and caches only to the active Lunch Money user and budgeting-account connection. Disconnecting a budgeting account should revoke continuing access for that connection and remove its locally stored credentials while keeping the active user's other connections intact. If the active user's final connection is removed, enter a disconnected state rather than falling back to another Lunch Money user's hidden connection.
+
+On application sign-out or Lunch Money user switching, clear session-specific selections and displayed or cached data so the newly active identity cannot see the previous identity's information. An application may retain the previous Lunch Money user's encrypted credentials when its ownership model permits it, but those connections must remain hidden and unavailable until that identity becomes active again. It may instead delete credentials during its own sign-out or switching lifecycle; that is an application policy.
+
+Keep remote revocation and local credential deletion separate. A local-only “forget” action does not end the remote authorization, so confirm that action and explain that access remains active at Lunch Money. Signing out of your application, hiding a retained connection, forgetting a local credential, and disconnecting Lunch Money are distinct lifecycle events.
 
 The [confidential Node.js sample](/oauth/sample-applications#understand-the-confidential-teaching-code) makes this boundary explicit in its [`CredentialStore`](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/main/src/oauth/tokens.ts) abstraction. Its [security guide](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/main/SECURITY.md) explains the threat model, and its [production checklist](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/main/PRODUCTION_CHECKLIST.md) lists the storage, tenant-isolation, lifecycle, and operational work the teaching sample deliberately omits. Those boundaries matter, but their implementation and database schema are specific to your application.
 

package/docs/oauth/tokens.md

@@ -18,13 +18,13 @@ A refresh token is issued after a successful authorization-code exchange only wh
 
 The [confidential Node.js sample](/oauth/sample-applications#try-oauth-with-your-lunch-money-account) keeps refresh optional within its first-run walkthrough. Register the sample client with `offline_access` to exercise the refresh branch, or omit it to focus on authorization, `GET /v2/me`, revocation, and reauthorization.
 
-Send a form-encoded `grant_type=refresh_token` request to the discovered token endpoint. Confidential clients authenticate with `client_secret_basic`; public clients send their client ID without a secret. A refresh never expands or switches the grant's registered scopes.
+Send a form-encoded `grant_type=refresh_token` request to the discovered token endpoint. Confidential clients authenticate with `client_secret_basic`; public clients send their client ID without a secret. A refresh never expands or switches the grant's registered scopes, Lunch Money user, or budgeting-account identity.
 
-Atomically persist the complete replacement token set before discarding the previous value, and serialize refreshes for each application-user connection. Lunch Money rotates refresh tokens; replay of a consumed token can invalidate the token family. Treat transient failures according to a bounded retry policy, but treat `invalid_grant` as terminal: delete unusable credentials and start a fresh authorization.
+Atomically persist the complete replacement token set before discarding the previous value, and serialize refreshes for each active application-user and Lunch Money user/account connection. Lunch Money rotates refresh tokens; replay of a consumed token can invalidate the token family. Treat transient failures according to a bounded retry policy, but treat `invalid_grant` as terminal: delete unusable credentials for that connection and start a fresh authorization.
 
 ## Revoke access
 
-Send the token to the discovered revocation endpoint using the authentication method appropriate to the client. Revocation returns success without revealing unnecessary token state. Locally discard the access token, refresh token, and related session state even if the network response is ambiguous.
+Send the active connection's token to the discovered revocation endpoint using the authentication method appropriate to the client. Revocation returns success without revealing unnecessary token state. Locally discard that connection's access token, refresh token, and related session state even if the network response is ambiguous. Keep other user/account connections unchanged.
 
 > [!TIP] Revocation endpoint
 > The currently resolved endpoint is `https://api.lunchmoney.dev/oauth/revoke`. Use authorization-server discovery to configure deployed applications so they receive the current endpoint automatically.
@@ -59,7 +59,9 @@ Do not paste a real client secret or token directly into a command where it may
 
 Revocation is different from expiration: expiration ends one credential naturally, while revocation deliberately removes access. Deleting or disabling an application and loss of user access can also make tokens unusable.
 
-A Lunch Money user can also revoke an application's access from the [Connected Apps page](https://my.lunchmoney.app/connected-apps). User revocation applies to the selected budgeting-account connection. Your application should treat the resulting authentication failure as terminal for that connection and ask the user to authorize it again when they want to reconnect. Keep connections to different Lunch Money budgeting accounts for the same application user independent.
+A Lunch Money user can also revoke an application's access from the [Connected Apps page](https://my.lunchmoney.app/connected-apps). User revocation applies to the selected Lunch Money user and budgeting-account authorization. Your application should treat the resulting authentication failure as terminal for that connection and ask the user to authorize it again when they want to reconnect. Keep every stored Lunch Money user/account connection independent, including when two users have authorized the same shared `account_id`.
+
+Remote revocation is different from local credential deletion. If an application offers a local-only “forget” action, confirm it and explain that the remote authorization remains active. Removing the active user's final local connection should leave the application disconnected rather than expose a hidden connection belonging to another Lunch Money user.
 
 ## Recovery rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunch-money/developer-docs",
-  "version": "2.11.2-preview.4",
+  "version": "2.11.2-preview.6",
   "description": "Developer documentation content for Lunch Money APIs",
   "exports": {
     ".": "./package.json",

package/v2/images/oauth-authorization-flow.svg

@@ -1,6 +1,6 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="1120" height="780" viewBox="0 0 1120 780" role="img" aria-labelledby="title desc">
+<svg xmlns="http://www.w3.org/2000/svg" width="1120" height="960" viewBox="0 0 1120 960" role="img" aria-labelledby="title desc">
   <title id="title">Lunch Money OAuth authorization-code flow</title>
-  <desc id="desc">A sequence diagram with three actors: your application, the Lunch Money user, and Lunch Money. The application redirects the user's browser to Lunch Money. When necessary, Lunch Money presents its sign-in screen and the user signs in directly with Lunch Money. Lunch Money then presents the budgeting-account selector and requested permissions, the user selects an account and approves access, Lunch Money returns an authorization code, and the application exchanges it for tokens and calls the API.</desc>
+  <desc id="desc">A sequence diagram with three actors: your application, the Lunch Money user, and Lunch Money. The application redirects the user's browser to Lunch Money. When necessary, Lunch Money presents its sign-in screen and the user signs in directly with Lunch Money. Lunch Money then presents the budgeting-account selector and requested permissions, the user selects an account and approves access, Lunch Money returns an authorization code, and the application exchanges it for tokens. The application calls GET /v2/me, saves the identified connection, and calls the API for that account.</desc>
   <defs>
     <marker id="app-arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#b45309"/></marker>
     <marker id="user-arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#9a6700"/></marker>
@@ -18,7 +18,7 @@
   <text class="actor-label" x="560" y="56" text-anchor="middle">Lunch Money user</text><text class="actor-detail" x="560" y="79" text-anchor="middle">browser, sign-in, and approval</text>
   <rect class="actor lm" x="820" y="25" width="260" height="72" rx="12"/>
   <text class="actor-label" x="950" y="56" text-anchor="middle">Lunch Money</text><text class="actor-detail" x="950" y="79" text-anchor="middle">authorization server and API</text>
-  <path class="lifeline" d="M170 105 V750"/><path class="lifeline" d="M560 105 V750"/><path class="lifeline" d="M950 105 V750"/>
+  <path class="lifeline" d="M170 105 V930"/><path class="lifeline" d="M560 105 V930"/><path class="lifeline" d="M950 105 V930"/>
   <path class="flow app-flow" d="M170 140 H550"/><rect class="step-bg" x="278" y="118" width="180" height="28" rx="6"/><text class="step" x="368" y="137" text-anchor="middle">1. Redirect the user</text>
   <path class="flow user-flow" d="M560 200 H940"/><rect class="step-bg" x="652" y="178" width="196" height="28" rx="6"/><text class="step" x="750" y="197" text-anchor="middle">2. Request authorization</text>
   <path class="flow lm-flow" d="M950 260 H570"/><rect class="step-bg" x="640" y="238" width="240" height="28" rx="6"/><text class="step" x="760" y="257" text-anchor="middle">3. Show sign-in, when needed</text>
@@ -28,5 +28,8 @@
   <path class="flow lm-flow" d="M950 500 H180"/><rect class="step-bg" x="385" y="478" width="360" height="28" rx="6"/><text class="step" x="565" y="497" text-anchor="middle">7. Redirect to callback with authorization code</text>
   <path class="flow app-flow" d="M170 580 H940"/><rect class="step-bg" x="335" y="558" width="460" height="28" rx="6"/><text class="step" x="565" y="577" text-anchor="middle">8. Exchange code with PKCE (+ client secret for confidential client)</text>
   <path class="flow lm-flow" d="M950 640 H180"/><rect class="step-bg" x="385" y="618" width="360" height="28" rx="6"/><text class="step" x="565" y="637" text-anchor="middle">9. Return access token + optional refresh token</text>
-  <path class="flow app-flow" d="M170 710 H940"/><rect class="step-bg" x="400" y="688" width="330" height="28" rx="6"/><text class="step" x="565" y="707" text-anchor="middle">10. Call the V2 API for that user and account</text>
+  <path class="flow app-flow" d="M170 700 H940"/><rect class="step-bg" x="430" y="678" width="270" height="28" rx="6"/><text class="step" x="565" y="697" text-anchor="middle">10. Call GET /v2/me</text>
+  <path class="flow lm-flow" d="M950 760 H180"/><rect class="step-bg" x="350" y="738" width="430" height="28" rx="6"/><text class="step" x="565" y="757" text-anchor="middle">11. Return user id, account_id, and budget_name</text>
+  <path class="flow app-flow" d="M170 800 H330 V840 H180"/><rect class="step-bg" x="285" y="798" width="330" height="28" rx="6"/><text class="step" x="450" y="817" text-anchor="middle">12. Save connection and make it active</text>
+  <path class="flow app-flow" d="M170 890 H940"/><rect class="step-bg" x="385" y="868" width="360" height="28" rx="6"/><text class="step" x="565" y="887" text-anchor="middle">13. Call the V2 API for the active account</text>
 </svg>