@lunch-money/developer-docs 2.11.2-preview.1 → 2.11.2-preview.11

package/docs/oauth/sample-applications.md

@@ -0,0 +1,263 @@
+# OAuth sample applications
+
+Use a sample application to see Lunch Money OAuth working end to end before you adapt the flow to your own architecture. Choose the confidential sample when a trusted server will hold credentials, or the native sample when an installed iOS or Android application will hold them. The two architectures have different security boundaries and are documented separately.
+
+> [!TIP] Open-source samples
+> - [Confidential Node.js and TypeScript sample](https://github.com/lunch-money/lm-oauth-confidential-node-example) and its [README](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/main/README.md)
+> - [Native Expo sample for iOS and Android](https://github.com/lunch-money/lm-oauth-native-expo-example) and its [README](https://github.com/lunch-money/lm-oauth-native-expo-example/blob/main/README.md)
+
+## Confidential Node.js and TypeScript sample
+
+> [!NOTE] This walkthrough is for confidential applications
+> The walkthrough and teaching-code guide below apply to the confidential Node.js sample, where a trusted server holds the client secret and credentials. For an installed iOS or Android application that holds its own credentials without a client secret, skip to the [Native Expo sample](#native-expo-sample).
+
+[`lm-oauth-confidential-node-example`](https://github.com/lunch-money/lm-oauth-confidential-node-example) is a teaching sample for a **confidential, server-side web client**. It uses Node.js, TypeScript, and the maintained [`openid-client`](https://github.com/panva/openid-client) library to demonstrate:
+
+- configuring a registered Lunch Money OAuth client and discovering authorization-server metadata;
+- starting authorization with single-use `state` and S256 Proof Key for Code Exchange (PKCE);
+- validating the callback and exchanging the code on the server;
+- calling `GET /v2/me` with a server-held access token;
+- optionally refreshing and atomically replacing the credential set for a client registered with `offline_access`;
+- revoking the access token and verifying that Lunch Money rejects it; and
+- resetting only the sample's local state so the flow can be repeated.
+
+> [!WARNING] Teaching sample, not a production application
+> The sample uses a fixed demonstration user and in-memory stores. It does not provide real application authentication, durable multi-user isolation, production credential storage, deployment configuration, or operational controls. Review its [security guidance](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/main/SECURITY.md) and [production checklist](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/main/PRODUCTION_CHECKLIST.md) before adapting any part of it.
+
+<!-- BEGIN GENERATED OAUTH SAMPLE WALKTHROUGH -->
+<!-- Source: lunch-money/lm-oauth-confidential-node-example@567516d5e32d89576323119bec7f40a7bee007b7:docs/WALKTHROUGH.md -->
+## Try OAuth with your Lunch Money account
+
+Use this walkthrough to authorize a real Lunch Money OAuth client, call the Lunch Money API, optionally refresh its credentials, revoke access, and repeat the flow. The sample is a confidential, server-side web client built with Node.js and TypeScript.
+
+[`openid-client`](https://github.com/panva/openid-client) is the recommended and supported third-party Node.js library for working with Lunch Money's OAuth interfaces. The sample uses it for discovery, authorization, callback validation, token exchange, refresh, and revocation while keeping every credential on the server.
+
+> [!IMPORTANT]
+> This is a real OAuth flow. You will create a real client, authorize access to a real Lunch Money budgeting account, receive real credentials, and call the real Lunch Money API. Only the automated tests use mocked Lunch Money responses.
+
+### Before you begin
+
+You need:
+
+- a Lunch Money account;
+- Node.js 20 or newer;
+- npm 11.6.2; and
+- Git.
+
+While a client is in development, only the Lunch Money user who created it can authorize it. Use that same Lunch Money user when the sample sends you through authorization. Other Lunch Money users can authorize the client only after it has been [reviewed and approved](https://lunchmoney.dev/oauth/review-and-approval).
+
+Three actions and identities are involved:
+
+- **A real Lunch Money user creates the client.** You create a real confidential OAuth client in the Developer Portal using your Lunch Money account. While the client is in development, only that same Lunch Money user can authorize it.
+- **That same Lunch Money user authorizes the client.** When you run the sample, you sign into Lunch Money, select one of your real budgeting accounts, and grant the client real access. The sample receives real tokens and uses them to call the real Lunch Money API.
+- **Only the sample application's user is simulated.** Most confidential web applications have their own users and login system. They must associate each Lunch Money authorization and its credentials with the correct application user. To demonstrate that boundary without building an unrelated login system, the sample uses a fixed internal identity named `local-demo-user`. A production application replaces it with an application-specific ID obtained from its authenticated server-side session. The ID should identify the user without using an email address or other personally identifiable information.
+
+```text
+Your real Lunch Money account
+  creates and owns the OAuth client
+  authorizes access to a real budgeting account
+                    ↓
+          Sample OAuth callback
+                    ↓
+Credentials stored under local-demo-user
+(the stand-in for your application's authenticated user)
+```
+
+The sample uses the client you register in the steps below; it does not create or modify that client. Client management remains in the Developer Portal. The automated tests use mocked HTTP responses, but the running sample connects to the configured real Lunch Money authorization and API services.
+
+### 1. Download and install the sample
+
+```sh
+git clone https://github.com/lunch-money/lm-oauth-confidential-node-example.git
+cd lm-oauth-confidential-node-example
+npm ci
+npm run build
+```
+
+### 2. Register a confidential client
+
+In the Lunch Money Developer Portal, create a **Confidential web client** with:
+
+- the exact redirect URI `http://localhost:4002/oauth/callback`;
+- the required `me:read` scope;
+- optionally, `offline_access` if you also want to exercise refresh; and
+- a client secret that you save securely when Lunch Money displays it.
+
+Lunch Money uses the complete scope set registered for the client. The sample therefore does not send a `scope` parameter during authorization.
+
+Registered scopes cannot be changed. Decide whether you want to test refresh before creating the client: adding `offline_access` later requires a replacement client registered with both `me:read` and `offline_access`, followed by a new authorization.
+
+You do not need `offline_access` to authorize the client, call `/v2/me`, revoke access, or authorize again.
+
+### 3. Configure the local process
+
+In the same terminal, set the client ID and secret from the Developer Portal:
+
+```sh
+export OAUTH_CLIENT_ID='YOUR_CLIENT_ID'
+export OAUTH_CLIENT_SECRET='YOUR_CLIENT_SECRET'
+export OAUTH_REDIRECT_URI='http://localhost:4002/oauth/callback'
+export LUNCH_MONEY_API_BASE_URL='{{LUNCH_MONEY_API_BASE_URL}}'
+```
+
+The Developer Portal replaces `{{LUNCH_MONEY_API_BASE_URL}}` with the API base URL for the environment where you registered the client, so the alpha guide configures alpha explicitly. If you are reading this walkthrough in the sample repository with a production client, omit the `LUNCH_MONEY_API_BASE_URL` export; the sample defaults to `https://api.lunchmoney.dev`. For a beta or alpha client, use the exact URL supplied by Lunch Money. The client registration and API base URL must belong to the same environment. The sample uses that value for OAuth discovery, token operations, and Lunch Money API requests. A real application should also use [OAuth discovery](https://lunchmoney.dev/oauth/authorization-code#configure-lunch-money-with-discovery) instead of hard-coding authorization, token, and revocation endpoint URLs. `PORT` is optional and defaults to `4002`.
+
+`SESSION_SECRET` is also optional for this local sample. If it is absent, the process creates a new random cookie-signing secret when it starts. Because all browser sessions, authorization attempts, and credentials are held in memory and cleared on restart, the generated secret can be cleared at the same time. A production application must instead provide a strong `SESSION_SECRET`, keep it stable across restarts, and not rotate it for each OAuth authorization.
+
+Alternatively, copy [`env.example`](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/567516d5e32d89576323119bec7f40a7bee007b7/env.example) to `.env` as described in [Load settings from a `.env` file](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/567516d5e32d89576323119bec7f40a7bee007b7/README.md#load-settings-from-a-env-file).
+
+> [!WARNING]
+> **Keep credentials private**
+> Keep the client secret in a private local environment or secret manager. Never paste it into documentation, AI chats or prompts, committed files, screenshots, browser code, logs, support requests, or commands retained in shared shell history.
+
+### 4. Start the sample
+
+```sh
+npm run dev
+```
+
+Open [http://localhost:4002](http://localhost:4002) in your browser.
+
+If a form reports **Invalid CSRF token**, reload the page and try again. This commonly happens when the development server restarts and clears its in-memory browser session while an older page remains open. Simply leaving the unchanged running sample open does not expire the form token.
+
+### 5. Authorize and call `/v2/me`
+
+1. Choose **Connect Lunch Money**.
+2. Sign into Lunch Money as the user who created the development client.
+3. Select one of that user's budgeting accounts and approve access.
+4. After the browser returns to `http://localhost:4002/oauth/callback`, expand **How this authorization was processed** to follow the callback, server-side code exchange, `/v2/me` identity check, and resulting active-user decision. Then choose **Call /v2/me**.
+
+The sample calls `GET /v2/me` from its Node.js server using the server-held access token. It validates the response against the documented `userObject` schema and displays the returned profile fields. The access token is never sent to the browser.
+
+The processing panel links each teaching step to its implementation. It deliberately does not reveal credential values. To see the normalized credential response while developing locally, set a debugger breakpoint immediately after `exchangeCallback()` returns in `completeAuthorization`, then inspect `tokenSet`. Do not print tokens in browser output or logs.
+
+If you want to verify the access token outside the sample, copy it from the local debugger and read it silently into a temporary shell variable. This keeps the credential itself out of shell history:
+
+```sh
+read -s LM_ACCESS_TOKEN
+curl --fail-with-body \
+  --header "Authorization: Bearer ${LM_ACCESS_TOKEN}" \
+  "${LUNCH_MONEY_API_BASE_URL}/v2/me"
+unset LM_ACCESS_TOKEN
+```
+
+Press <kbd>Enter</kbd> after pasting the token at the hidden prompt. Treat it as a live secret: use a private local terminal, do not paste it directly into a command, and clear the variable when finished. This debugger workflow is for understanding and testing the sample. A production application should inspect encrypted credential records only through privileged operational tooling that redacts secret values.
+
+Open Lunch Money's [Connected Apps](https://my.lunchmoney.app/connected-apps) page in another tab, keeping the sample available so you can return to it. The client you just authorized should appear with the details you registered. If you plan to exercise refresh, return to the sample without revoking access yet; revocation ends this authorization's continuing access.
+
+### 6. Optionally refresh access
+
+If you registered the client with `offline_access`, choose **Refresh access token**, then choose **Call /v2/me** again.
+
+Lunch Money replaces both the access token and refresh token after a successful refresh. The sample stores the complete replacement credential set on the server before reporting success. Calling `/v2/me` again confirms that it is using the replacement access token.
+
+If you registered only `me:read`, Lunch Money does not issue a refresh token and the refresh button does not appear. Skip this step.
+
+The sample allows an immediate refresh so you can observe the flow. A production application normally decides when to refresh using expiration information from the token response or after an API authentication failure.
+
+### 7. Disconnect the active budget
+
+Choose **Disconnect active budget**.
+
+- If the connection has a refresh token, the sample revokes it to revoke the entire grant.
+- If the connection has only an access token, the sample revokes that access token.
+
+The sample then calls `/v2/me` with the old access token, requires Lunch Money to return `401`, and deletes its locally stored credential. This verification demonstrates that the old access token no longer works.
+
+To repeat the flow, choose **Connect Lunch Money** and authorize the client again.
+
+### 8. Try user-initiated revocation
+
+To see what happens when a Lunch Money user disconnects the client:
+
+1. Authorize the sample again.
+2. Open [Connected Apps](https://my.lunchmoney.app/connected-apps). Keep the sample available in another tab so you can return to it after revoking the authorization.
+3. Revoke the client's access there.
+4. Return to the sample and choose **Call /v2/me**.
+
+The request should fail because Lunch Money no longer accepts the stored access token. Choose **Forget local credential only** to remove the now-unusable local credential before starting again.
+
+### Local reset is not revocation
+
+**Forget local credential only** clears the active budget's locally stored credential after confirmation. It does not contact Lunch Money and does not revoke active access.
+
+When access is still active, revoke it first through **Disconnect active budget** or Lunch Money's Connected Apps page. Forget the local credential by itself only when the remote authorization has already been revoked or you deliberately want to clear this disposable local demonstration.
+
+### Why `localhost` works
+
+> [!NOTE]
+> Lunch Money redirects your browser to the registered callback, and your browser connects to the sample running on your computer. Lunch Money's server does not initiate a connection to `localhost`, so this walkthrough does not require a public deployment or tunnel.
+
+### Keep the sample local
+
+> [!WARNING]
+> The sample uses a fixed application identity and keeps browser sessions, authorization attempts, credentials, and refresh coordination in memory. Run it locally and do not expose it as a public application. Use a test budgeting account when practical. Restarting the sample clears its in-memory state.
+
+After the flow succeeds, connect each action you performed to the code that implemented it, then decide how those responsibilities fit into your own application.
+
+Before adapting the code, read the repository's [OAuth code guide](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/567516d5e32d89576323119bec7f40a7bee007b7/src/oauth/README.md), [security model](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/567516d5e32d89576323119bec7f40a7bee007b7/SECURITY.md), [production checklist](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/567516d5e32d89576323119bec7f40a7bee007b7/PRODUCTION_CHECKLIST.md), and [troubleshooting guide](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/567516d5e32d89576323119bec7f40a7bee007b7/TROUBLESHOOTING.md).
+<!-- END GENERATED OAUTH SAMPLE WALKTHROUGH -->
+
+## Understand the confidential teaching code
+
+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 budget-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.
+
+### Follow the flow through the source
+
+Start with the [`src/oauth` guide](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/main/src/oauth/README.md). It provides the maintained reading order for the framework-independent OAuth modules and connects each file to the stage of the flow it implements.
+
+The OAuth teaching code is isolated under `src/oauth`. Hono, sessions, cookies, pages, and other runnable presentation code live under `src/scaffolding`, so you can replace the framework without obscuring the protocol flow. The sample's [architecture guide](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/main/ARCHITECTURE.md) explains this boundary, and its [OAuth tests](https://github.com/lunch-money/lm-oauth-confidential-node-example/tree/main/tests/oauth) mirror the recommended reading order, including focused [refresh tests](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/main/tests/oauth/refresh.test.ts). If your result differs, compare the stage that failed with the sample's [troubleshooting guide](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/main/TROUBLESHOOTING.md) and the public [OAuth troubleshooting guide](/oauth/troubleshooting).
+
+## Native Expo sample
+
+Choose [`lm-oauth-native-expo-example`](https://github.com/lunch-money/lm-oauth-native-expo-example) for an iOS or Android application installed
+on the user's device when there is no trusted backend that can hold a client
+secret. It uses Expo, the platform authentication browser, authorization code
+with S256 PKCE, and platform secure storage as a native/public client. Its
+optional `offline_access` path demonstrates rotated refresh credentials and
+terminal reauthorization without introducing a backend or client secret.
+
+Do not choose it merely because your interface is responsive. Choose it because
+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 budget-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 sample defaults to the production API at
+`https://api.lunchmoney.dev`. This Developer Portal is configured for
+`{{LUNCH_MONEY_API_BASE_URL}}`. If this differs from production, set the
+sample's API-base override before starting it:
+
+```sh
+export EXPO_PUBLIC_LUNCH_MONEY_API_BASE_URL='{{LUNCH_MONEY_API_BASE_URL}}'
+```
+
+Register the OAuth client in the same environment as that API base URL. A
+client registration from one environment cannot be used with another
+environment's authorization server and API.
+
+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.
+
+### Follow the native flow through the source
+
+Start with the native sample's [`src/oauth` guide](https://github.com/lunch-money/lm-oauth-native-expo-example/blob/main/src/oauth/README.md). It provides the maintained reading order from public configuration and Expo's system-browser adapter through callback validation, secure credential storage, optional refresh, revocation, and the workflow connected to the sample screen.
+
+The OAuth teaching code is isolated under `src/oauth`; React Native UI and platform storage adapters live under `src/scaffolding`. Use the sample's [OAuth tests](https://github.com/lunch-money/lm-oauth-native-expo-example/tree/main/tests) to follow the expected success and failure behavior, then review its [security guidance](https://github.com/lunch-money/lm-oauth-native-expo-example/blob/main/SECURITY.md) and [production checklist](https://github.com/lunch-money/lm-oauth-native-expo-example/blob/main/PRODUCTION_CHECKLIST.md) before adapting it.
+
+Next: [Develop and test your OAuth application](/oauth/development) and [operate it securely](/oauth/security).

package/docs/oauth/scopes.md

@@ -1,13 +1,13 @@
 # OAuth scopes
 
-Choose the smallest complete set of permissions your application needs. This page is generated from the published `@lunch-money/v2-api-spec/oauth-scopes` catalog; do not edit it by hand.
+Scopes are named permissions that define what an OAuth client may do with Lunch Money data. Choose the smallest complete set of scopes your application needs. This page is generated from the published `@lunch-money/v2-api-spec/oauth-scopes` catalog; do not edit it by hand.
 
 > [!NOTE] Scopes are fixed when you create a client
-> Authorization requests omit `scope`. To change permissions later, create and review a replacement client, update your integration, and ask every user to authorize it.
+> Authorization requests omit `scope`. To change scopes later, create and review a replacement client, update your integration, and ask every user to authorize it.
 
 ## Scope groups
 
-Groups are selection shortcuts, not extra permissions. A group expands to the exact scopes listed below.
+Groups are selection shortcuts, not additional scopes. Every predefined group includes `me:read` so an application can identify the authorized Lunch Money user and budget account. A group expands to the exact scopes listed below.
 
 ### Read only
 
@@ -19,25 +19,25 @@ View all supported Lunch Money data without changing it
 
 Import, export, organize, and manage transactions and their attachments
 
-[`transactions:read`](#scope-transactions-read), [`transactions:create`](#scope-transactions-create), [`transactions:update`](#scope-transactions-update), [`transactions:delete`](#scope-transactions-delete), [`transaction_attachments:read`](#scope-transaction-attachments-read), [`transaction_attachments:create`](#scope-transaction-attachments-create), [`transaction_attachments:delete`](#scope-transaction-attachments-delete), [`categories:read`](#scope-categories-read), [`tags:read`](#scope-tags-read), [`manual_accounts:read`](#scope-manual-accounts-read), [`plaid_accounts:read`](#scope-plaid-accounts-read), [`recurring_items:read`](#scope-recurring-items-read)
+[`me:read`](#scope-me-read), [`transactions:read`](#scope-transactions-read), [`transactions:create`](#scope-transactions-create), [`transactions:update`](#scope-transactions-update), [`transactions:delete`](#scope-transactions-delete), [`transaction_attachments:read`](#scope-transaction-attachments-read), [`transaction_attachments:create`](#scope-transaction-attachments-create), [`transaction_attachments:delete`](#scope-transaction-attachments-delete), [`categories:read`](#scope-categories-read), [`tags:read`](#scope-tags-read), [`manual_accounts:read`](#scope-manual-accounts-read), [`plaid_accounts:read`](#scope-plaid-accounts-read), [`recurring_items:read`](#scope-recurring-items-read)
 
 ### Budgeting
 
 Analyze and manage budgets, categories, and tags
 
-[`summary:read`](#scope-summary-read), [`budgets:read`](#scope-budgets-read), [`budgets:update`](#scope-budgets-update), [`budgets:delete`](#scope-budgets-delete), [`categories:read`](#scope-categories-read), [`categories:create`](#scope-categories-create), [`categories:update`](#scope-categories-update), [`categories:delete`](#scope-categories-delete), [`tags:read`](#scope-tags-read), [`tags:create`](#scope-tags-create), [`tags:update`](#scope-tags-update), [`tags:delete`](#scope-tags-delete), [`recurring_items:read`](#scope-recurring-items-read)
+[`me:read`](#scope-me-read), [`summary:read`](#scope-summary-read), [`budgets:read`](#scope-budgets-read), [`budgets:update`](#scope-budgets-update), [`budgets:delete`](#scope-budgets-delete), [`categories:read`](#scope-categories-read), [`categories:create`](#scope-categories-create), [`categories:update`](#scope-categories-update), [`categories:delete`](#scope-categories-delete), [`tags:read`](#scope-tags-read), [`tags:create`](#scope-tags-create), [`tags:update`](#scope-tags-update), [`tags:delete`](#scope-tags-delete), [`recurring_items:read`](#scope-recurring-items-read)
 
 ### Accounts
 
 Manage accounts, balances, and balance history
 
-[`manual_accounts:read`](#scope-manual-accounts-read), [`manual_accounts:create`](#scope-manual-accounts-create), [`manual_accounts:update`](#scope-manual-accounts-update), [`manual_accounts:delete`](#scope-manual-accounts-delete), [`plaid_accounts:read`](#scope-plaid-accounts-read), [`plaid_accounts:update`](#scope-plaid-accounts-update), [`crypto_manual:read`](#scope-crypto-manual-read), [`crypto_manual:create`](#scope-crypto-manual-create), [`crypto_manual:update`](#scope-crypto-manual-update), [`crypto_manual:delete`](#scope-crypto-manual-delete), [`crypto_synced:read`](#scope-crypto-synced-read), [`crypto_synced:update`](#scope-crypto-synced-update), [`balance_history:read`](#scope-balance-history-read), [`balance_history:update`](#scope-balance-history-update), [`balance_history:delete`](#scope-balance-history-delete)
+[`me:read`](#scope-me-read), [`manual_accounts:read`](#scope-manual-accounts-read), [`manual_accounts:create`](#scope-manual-accounts-create), [`manual_accounts:update`](#scope-manual-accounts-update), [`manual_accounts:delete`](#scope-manual-accounts-delete), [`plaid_accounts:read`](#scope-plaid-accounts-read), [`plaid_accounts:update`](#scope-plaid-accounts-update), [`crypto_manual:read`](#scope-crypto-manual-read), [`crypto_manual:create`](#scope-crypto-manual-create), [`crypto_manual:update`](#scope-crypto-manual-update), [`crypto_manual:delete`](#scope-crypto-manual-delete), [`crypto_synced:read`](#scope-crypto-synced-read), [`crypto_synced:update`](#scope-crypto-synced-update), [`balance_history:read`](#scope-balance-history-read), [`balance_history:update`](#scope-balance-history-update), [`balance_history:delete`](#scope-balance-history-delete)
 
 ### Organize
 
 Manage categories and tags used to organize transactions
 
-[`categories:read`](#scope-categories-read), [`categories:create`](#scope-categories-create), [`categories:update`](#scope-categories-update), [`categories:delete`](#scope-categories-delete), [`tags:read`](#scope-tags-read), [`tags:create`](#scope-tags-create), [`tags:update`](#scope-tags-update), [`tags:delete`](#scope-tags-delete), [`recurring_items:read`](#scope-recurring-items-read)
+[`me:read`](#scope-me-read), [`categories:read`](#scope-categories-read), [`categories:create`](#scope-categories-create), [`categories:update`](#scope-categories-update), [`categories:delete`](#scope-categories-delete), [`tags:read`](#scope-tags-read), [`tags:create`](#scope-tags-create), [`tags:update`](#scope-tags-update), [`tags:delete`](#scope-tags-delete), [`recurring_items:read`](#scope-recurring-items-read)
 
 ### Full access
 

package/docs/oauth/security.md

@@ -20,7 +20,37 @@ Keeping access tokens on the server reduces their exposure to browser code. Usin
 
 In the browser-based model, the short-lived access token is also visible to the signed-in user in the request's `Authorization` header. That visibility is expected and is not, by itself, a credential leak. The tradeoff is that a malicious script running on the page—or someone with access to that browser session—could copy the bearer token and use it until it expires or is revoked.
 
-If your browser code uses access tokens, keep them available for no longer than necessary, avoid persistent browser storage when practical, and protect the application against cross-site scripting. Regardless of the architecture, keep the client secret and refresh tokens on the server, never put bearer tokens in URLs or logs, and associate each authorization with the correct application user and Lunch Money budgeting account.
+If your browser code uses access tokens, keep them available for no longer than necessary, avoid persistent browser storage when practical, and protect the application against cross-site scripting. Regardless of the architecture, keep the client secret and refresh tokens on the server, never put bearer tokens in URLs or logs, and associate each authorization with the correct application user and Lunch Money budget account.
+
+## Associate credentials with your application user
+
+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 budget-account connection under a stable internal application-user ID. Within that owner, use both the Lunch Money user `id` and budget-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
+  -> owned connection (Lunch Money user id + account_id)
+     -> encrypted credential set
+```
+
+When the user returns to your application, authenticate them through your application's own sign-in system before listing or using their saved connections. Knowing a Lunch Money `id`, `account_id`, or internal connection ID does not prove ownership. Limit connection lookups to the authenticated application user's records, and reject requests for a connection they do not own before loading its credentials.
+
+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 budget account. Each application user must authorize their own connection. If Alex has authorized two budget 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 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.
+
+Apply API calls, refresh, revocation, local deletion, and caches only to the active Lunch Money user and budget-account connection. Disconnecting a budget 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.
 
 ## Secure authorization and callbacks
 
@@ -37,7 +67,7 @@ Choose only the resource scopes needed for expected features. Add `offline_acces
 
 ## Operate credentials safely
 
-Rotate client secrets on a schedule appropriate for your application's risk and immediately when one may have been exposed. Use overlapping active secrets during a controlled rotation: create the replacement, deploy and verify it, and then revoke the old secret. Coordinate refreshes so two workers do not replay the same rotating token. Make logout revoke server-side credentials and clear local state.
+Rotate client secrets on a schedule appropriate for your application's risk and immediately when one may have been exposed. A client can have up to three non-revoked secrets, so confirm that it has room before starting a rotation. Expired secrets still count toward this limit until you revoke them. Use overlapping active secrets during a controlled rotation: create the replacement, deploy and verify it, and then revoke the old secret. Coordinate refreshes so two workers do not replay the same rotating token, and atomically persist every complete replacement credential set. Production storage needs database transactions, distributed per-connection locking, recovery when persistence fails, multi-instance coordination, and tenant isolation. Make disconnect invalidate continuing refresh access as well as clear local state.
 
 If a credential may have been exposed, stop using it, revoke it, rotate the relevant client secret, review logs without copying secret values, and require reauthorization when the grant can no longer be trusted.
 

package/docs/oauth/tokens.md

@@ -8,19 +8,23 @@ Teal boxes show the normal token lifecycle. The amber box marks a terminal failu
 
 ## Determine expiration
 
+Keep each token set associated with the application user and the authorized Lunch Money user and budget account pair. Renewing credentials does not change that pair; selecting another budget account requires a new authorization. See [users, budget accounts, and access tokens](/oauth/concepts#users-budget-accounts-and-access-tokens).
+
 Access tokens are deliberately short-lived. Record when the token response arrives and add its `expires_in` duration to determine the expected expiry. Refresh slightly before that point while accounting for clock skew. Do not parse the opaque access token or assume a fixed lifetime.
 
 ## Refresh access
 
 A refresh token is issued after a successful authorization-code exchange only when the registered client includes `offline_access`. It lasts longer than an access token, but it is not permanent.
 
-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.
+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, Lunch Money user, or budget-account identity.
 
-Persist every replacement refresh token before discarding the previous value, and serialize refreshes for a grant. Lunch Money rotates refresh tokens; replay of a consumed token can invalidate the token family. If refresh fails terminally, 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.
@@ -55,6 +59,10 @@ 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 Lunch Money user and budget-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
 
 - A rejected API request may mean the access token expired, was revoked, lacks the required scope, targets the wrong resource, or no longer maps to an accessible account. The `401` response does not identify which cause applies. Follow the [API failure decision tree](/oauth/troubleshooting#api-failures).

package/docs/oauth/troubleshooting.md

@@ -8,6 +8,8 @@ OAuth problems are usually easiest to resolve once you identify where the flow s
 
 When collecting diagnostic details, preserve nonsensitive information such as timestamps and error names, but leave credentials and full callback URLs out of logs and support messages.
 
+For a runnable comparison, [try OAuth with the confidential Node.js sample](/oauth/sample-applications#try-oauth-with-your-lunch-money-account). Reproduce the same stage in its end-to-end flow, then compare the result with the sample repository's [troubleshooting guide](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/main/TROUBLESHOOTING.md) without copying credentials or full callback URLs.
+
 > [!NOTE] Two error formats
 > OAuth protocol endpoints under `/oauth/` use lower-case OAuth error names such as `invalid_grant`. The v2 API uses the Lunch Money response format, with a `message` and an `errors` array whose entries contain `errMsg`.
 
@@ -82,12 +84,12 @@ If a successful authorization-code exchange does not include a refresh token, co
 Treat an OAuth `401` as an unknown access-token failure unless a refresh request establishes what happened. When an eligible refresh token is available, attempt one refresh and handle the token endpoint's result, which uses the OAuth format shown above rather than the v2 API format:
 
 1. On success, save the replacement tokens and retry the API request once. The access token had merely expired.
-2. On `invalid_grant`, treat the authorization as revoked: mark that user's Lunch Money connection as inactive and discard its tokens. Prompt the user to authorize again the next time they sign in rather than repeatedly interrupting them.
+2. On `invalid_grant`, treat that connection as revoked: mark the connection for the selected user/account as inactive and discard its tokens. Prompt the user to authorize that connection again the next time they need it rather than repeatedly interrupting them. Leave the user's other budget-account connections unchanged.
 3. On `invalid_client`, stop requests for every user of the client and contact [developer support](mailto:developer-support@lunchmoney.app). Lunch Money may have disabled the client; retrying or asking users to authorize again will not help.
 
 If no eligible refresh token is available, discard the rejected access token and ask the user to authorize again.
 
-An OAuth access token can fail because it expired, access was revoked, the client was disabled, the user reauthorized the application, a token was revoked or rotated, or the user lost access to the budgeting account. Every OAuth access-token failure returns the same generic `401` response:
+An OAuth access token can fail because it expired, access was revoked, the client was disabled, the token was revoked or rotated, or the user lost access to the budget account. Every OAuth access-token failure returns the same generic `401` response:
 
 ```http
 HTTP/1.1 401
@@ -127,12 +129,24 @@ WWW-Authenticate: Bearer error="insufficient_scope", scope="transactions:read"
 }
 ```
 
-The `scope` parameter names every scope the endpoint requires, including any the client may already have. It is not a list of only the missing scopes. Check the operation in the [V2 API reference](/v2/docs) or the [scope catalog](/oauth/scopes) to confirm its requirements.
+The `scope` parameter names every scope the endpoint requires, including any the client may already have. It is not a list of only the missing scopes. Check the operation in the [V2 API reference](/v2/docs) or [OAuth scopes](/oauth/scopes) to confirm its requirements.
 
 ### Replace a client to change scopes
 
 Adding `scope` to an authorization URL cannot upgrade or narrow a grant. Lunch Money ignores the requested value and uses the client's complete registered scope set. To change scopes, create a replacement client, test all functionality, complete any required review, update the deployed client ID and credentials, and send every existing user through authorization again.
 
+## Client-management failures
+
+The Developer Portal can return structured errors when you register clients, create client secrets, or submit a client for review. These errors use the Lunch Money response format, not OAuth protocol errors such as `invalid_grant`.
+
+| Status and code | Meaning | What to do |
+| --- | --- | --- |
+| `422 quota_exceeded`, field `clients` | You already own 25 non-deleted OAuth clients. | Delete a client you no longer use before registering another. |
+| `422 quota_exceeded`, field `secrets` | The client already has three non-revoked secrets. Expired secrets still count. | Revoke an obsolete or expired secret before creating another. |
+| `429 review_quota_exceeded` | You have made five initial review submissions across your clients in the rolling 24-hour window. | Wait until the time shown in the Developer Portal before submitting again. API clients should also respect the `Retry-After` response header. |
+
+Cancelled submissions, rejected-client resubmissions, and submissions for clients later deleted still count toward the review limit. Reviews opened automatically after an active client's identity changes do not count.
+
 ## Local callback failures
 
 For local development, use a supported loopback host: `localhost`, `127.0.0.1`, or `[::1]`. Matching depends on the client type:

package/manifest.json

@@ -105,6 +105,14 @@
       "type": "markdown",
       "aliases": ["/v2/oauth/authorization-code"]
     },
+    {
+      "path": "/oauth/sample-applications",
+      "file": "docs/oauth/sample-applications.md",
+      "title": "OAuth Sample Applications",
+      "section": "OAUTH",
+      "type": "markdown",
+      "aliases": ["/v2/oauth/sample-applications"]
+    },
     {
       "path": "/oauth/development",
       "file": "docs/oauth/development.md",
@@ -304,13 +312,14 @@
         { "label": "Concepts", "path": "/oauth/concepts" },
         { "label": "Register a Client", "path": "/oauth/register-client" },
         { "label": "Implement Authorization", "path": "/oauth/authorization-code" },
+        { "label": "Sample Applications", "path": "/oauth/sample-applications" },
         { "label": "Develop and Test", "path": "/oauth/development" },
         { "label": "Token Lifecycle", "path": "/oauth/tokens" },
         { "label": "Security", "path": "/oauth/security" },
         { "label": "Troubleshooting", "path": "/oauth/troubleshooting" },
         { "label": "Review and Approval", "path": "/oauth/review-and-approval" },
         { "label": "Native Apps", "path": "/oauth/native-apps" },
-        { "label": "Scope Catalog", "path": "/oauth/scopes" }
+        { "label": "Scopes", "path": "/oauth/scopes" }
       ]},
       { "section": "REFERENCE", "items": [
         { "label": "v2 API Overview", "path": "/v2/overview" },

package/package.json

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

package/v1/_user.md

@@ -11,8 +11,8 @@ This API (v1) will not progress to a generally available state. For new projects
 | user_id        | number | false    | Unique identifier for user                                                              |
 | user_name      | string | false    | User's name                                                                             |
 | user_email     | string | false    | User's email                                                                            |
-| account_id     | number | false    | Unique identifier for the associated budgeting account                                  |
-| budget_name    | string | false    | Name of the associated budgeting account                                                |
+| account_id     | number | false    | Unique identifier for the associated budget account                                     |
+| budget_name    | string | false    | Name of the associated budget account                                                   |
 | primary_currency|string | false    | Primary currency from user's settings                                                   |
 | api_key_label  | string | true     | User-defined label of the developer API key used. Returns null if nothing has been set. |
 

package/v2/docs/intro-to-v2.md

@@ -10,7 +10,7 @@ All API requests require a Bearer token in the `Authorization` header:
 Authorization: Bearer YOUR_ACCESS_TOKEN
 ```
 
-Use a personal access token for API exploration or work with your own budgeting account. The [Getting started guide](/getting-started) walks through creating one on the <a href="https://my.lunchmoney.app/developers" target="_blank" rel="noopener noreferrer">Lunch Money Developers page</a> and making your first request. Applications built for other Lunch Money users should use an [OAuth access token issued after the user authorizes the application](/oauth).
+Use a personal access token for API exploration or work with your own budget account. The [Getting started guide](/getting-started) walks through creating one on the <a href="https://my.lunchmoney.app/developers" target="_blank" rel="noopener noreferrer">Lunch Money Developers page</a> and making your first request. Applications built for other Lunch Money users should use an [OAuth access token issued after the user authorizes the application](/oauth).
 
 ## Base URL
 

package/v2/docs/version-history.md

@@ -7,13 +7,15 @@ The Lunch Money API spec uses a modified version of SEMVER for its versioning me
 
 ## v2.11.2 - TBD
 - Add OAuth 2.0 bearer-token authentication to the v2 API, allowing applications to access Lunch Money on behalf of users who authorize them
-- Enforce required OAuth scopes for every v2 operation and publish the scope and scope-group catalog mapped to V2 `operationId` values
+- Document and enforce required OAuth scopes for every v2 operation and publish the scope and scope-group catalog mapped to V2 `operationId` values.
+  - Added a new `403` `insufficient_scope` response
 - Document the OAuth 2.0 authorization-code flow used to obtain access tokens
+- Add `include_files` query parameter to `GET /transactions/{id}`
 
 ## v2.11.1 - TBD
 - Add `GET /me/account/settings` and `PUT /me/account/settings` for account-level settings
 - Add `GET /me/user/settings` and `PUT /me/user/settings` for user-level display and formatting preferences
-- Add `GET /me/user/account/settings` and `PUT /me/user/account/settings` for settings specific to a user and budgeting account
+- Add `GET /me/user/account/settings` and `PUT /me/user/account/settings` for settings specific to a user and budget account
 - Add `include_pending_in_totals` to `GET /me/account/settings` and `PUT /me/account/settings`
 - Add `default_manual_account_id` to `GET /me/user/account/settings` and `PUT /me/user/account/settings`
 - Document `GET /budgets/settings` response schema publicly; change `budget_period_quantity` to integer

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 budget-account selector and requested scopes, 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,15 +18,18 @@
   <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>
   <path class="flow user-flow" d="M560 320 H940"/><rect class="step-bg" x="605" y="298" width="290" height="28" rx="6"/><text class="step" x="750" y="317" text-anchor="middle">4. Sign in directly with Lunch Money</text>
-  <path class="flow lm-flow" d="M950 380 H570"/><rect class="step-bg" x="590" y="358" width="340" height="28" rx="6"/><text class="step" x="760" y="377" text-anchor="middle">5. Present account and permission choices</text>
-  <path class="flow user-flow" d="M560 440 H940"/><rect class="step-bg" x="585" y="418" width="330" height="28" rx="6"/><text class="step" x="750" y="437" text-anchor="middle">6. Select budgeting account and approve</text>
+  <path class="flow lm-flow" d="M950 380 H570"/><rect class="step-bg" x="545" y="358" width="430" height="28" rx="6"/><text class="step" x="760" y="377" text-anchor="middle">5. Present budget-account selector and scopes</text>
+  <path class="flow user-flow" d="M560 440 H940"/><rect class="step-bg" x="585" y="418" width="330" height="28" rx="6"/><text class="step" x="750" y="437" text-anchor="middle">6. Select budget account and approve</text>
   <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="466" y="688" width="198" height="28" rx="6"/><text class="step" x="565" y="707" text-anchor="middle">10. Call the V2 API</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>