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

package/docs/oauth/authorization-code.md

@@ -15,6 +15,8 @@ OAuth libraries handle much of the protocol work for you, including generating P
 
 For Node.js and TypeScript, [`openid-client`](https://github.com/panva/openid-client) is one maintained option. Despite its name, using it does not mean that Lunch Money supports OpenID Connect identity scopes, ID tokens, or UserInfo.
 
+The [confidential Node.js sample application](/oauth/sample-applications#understand-and-apply-the-teaching-code) shows this library in a complete Lunch Money flow. Begin with its [`src/oauth` guide](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/main/src/oauth/README.md), then follow the listed reading order from protocol types and discovery through authorization, callback validation, credential storage, API access, optional refresh, and revocation.
+
 ## Configure Lunch Money with discovery
 
 Your OAuth library needs to know where to send the user for authorization, where to exchange codes for tokens, and which protocol features Lunch Money supports. Instead of configuring each value separately, give the library the Lunch Money issuer:

package/docs/oauth/concepts.md

@@ -7,7 +7,7 @@ These terms describe who participates in Lunch Money OAuth and what each credent
 - **User (resource owner):** the Lunch Money user who authorizes a third-party application to make API requests on their behalf for one budgeting account.
 - **Application:** the complete product or service the developer builds. It may contain many features unrelated to Lunch Money; only its Lunch Money OAuth client is managed in the Developer Portal.
 - **Client:** the application's OAuth registration with Lunch Money: its `client_id`, type, redirect URIs, selected scopes, and—when applicable—client secret. The developer must register this client in the Developer Portal before the application can ask Lunch Money users to authorize API access.
-- **Authorization server:** the Lunch Money-owned service that presents the Lunch Money sign-in and consent screens, records the user's decision, and issues authorization codes and tokens. The user signs in directly with Lunch Money; the third-party application never receives or sees their Lunch Money login credentials.
+- **Authorization server:** the Lunch Money-owned service that presents the Lunch Money sign-in and consent screens, records the user's decision, and issues authorization codes and tokens. It also handles token requests, including exchanging authorization codes and refresh tokens for new tokens. The user signs in directly with Lunch Money; the third-party application never receives or sees their Lunch Money login credentials.
 - **Lunch Money API service:** the Lunch Money-owned V2 API, which receives the application's API requests, accepts access tokens, and checks that each request is permitted by the client's scopes.
 
 ## Client types and credentials
@@ -17,6 +17,8 @@ When a developer registers a client, they must choose a client type based on whe
 - **Confidential web client:** Runs on a server and can securely store client secrets. In OAuth terminology, this is called a *confidential client*. Choose this type for a web application—or any other application architecture with a centralized server. Its client secret helps Lunch Money verify that a token request came from the application that registered the client. The client secret and refresh tokens must stay on the server. The application must protect access tokens wherever its architecture uses them, and associate each authorization with the correct application user and authorized Lunch Money budgeting account.
 - **Native or public client:** Runs on a user-controlled device and uses PKCE without a client secret because installed application code cannot keep a secret secure. In OAuth terminology, this is called a *native public client*. Choose this type for a standalone mobile or desktop application. The app stores each user's tokens securely on that user's device—for example, in Keychain on Apple platforms or appropriate Keystore-backed storage on Android—and must avoid exposing them through backups, logs, or application data shared with other apps.
 
+These client families are not interchangeable. A confidential server-side sample cannot be moved into a native application by embedding its client secret or server-held credentials; use a native-client flow and platform secure storage instead.
+
 Every client receives a client ID that identifies its Lunch Money registration. The client ID is not secret. Both client types also use Proof Key for Code Exchange (PKCE) to bind the authorization response to the application that started the flow.
 
 ## Redirect URIs

package/docs/oauth/development.md

@@ -13,6 +13,8 @@ Use a separate Lunch Money test budgeting account when exercising create, update
 
 Keep production client secrets, tokens, and user data out of test fixtures, logs, screenshots, and bug reports.
 
+If you want a working reference flow for comparison, [try OAuth with the confidential Node.js sample](/oauth/sample-applications#try-oauth-with-your-lunch-money-account). Its `me:read` walkthrough helps validate client registration, exact local callback configuration, discovery, authorization, `GET /v2/me`, and revocation before you debug application-specific features. Add `offline_access` when registering the sample client only if you also want to exercise its optional refresh branch.
+
 ## Local loopback callbacks
 
 When you run a confidential web application on your own computer, its callback handler may not have a public HTTPS address yet. A loopback redirect lets the browser return the authorization result directly to the local process you are developing.

package/docs/oauth/index.md

@@ -25,4 +25,4 @@ An OAuth client is an application's registration with Lunch Money. When a develo
 
 You need an active Lunch Money account to [register and manage an OAuth client](/oauth/applications) for your application. During development, only the client owner can authorize the application. Approval is required before other Lunch Money users can authorize it.
 
-Start with [OAuth concepts](/oauth/concepts), [register a client](/oauth/register-client), and then [implement the authorization-code flow](/oauth/authorization-code). Use the [scope catalog](/oauth/scopes) to plan permissions and [troubleshooting](/oauth/troubleshooting) when a flow fails.
+Start with [OAuth concepts](/oauth/concepts), [register a client](/oauth/register-client), and then [implement the authorization-code flow](/oauth/authorization-code). You can also run the [confidential Node.js sample application](/oauth/sample-applications) to see registration, authorization, an API call, revocation, and local reset working together. Use the [scope catalog](/oauth/scopes) to plan permissions and [troubleshooting](/oauth/troubleshooting) when a flow fails.

package/docs/oauth/register-client.md

@@ -11,6 +11,8 @@ 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.
 
+For the confidential Node.js sample, always select `me:read`. Add `offline_access` only if you want to exercise its optional refresh branch; the rest of the walkthrough does not require it.
+
 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.
 
 If functionality added after launch needs a scope that is not already registered, you must register a replacement client with the new complete scope set and have it reviewed before rollout. Existing authorizations do not transfer to the replacement client, so users must authorize it before they can use the new functionality. Treat that reauthorization as part of the feature launch: explain what the application can now do with their Lunch Money data and invite them to authorize the replacement client when they want to enable it.
@@ -49,4 +51,6 @@ A confidential web client can have multiple active secrets. This allows you to i
 
 You now have the client settings needed to connect your application to Lunch Money.
 
+To exercise those settings with a focused confidential-client implementation, [try OAuth with the Node.js sample](/oauth/sample-applications#try-oauth-with-your-lunch-money-account).
+
 Next: [Implement authorization](/oauth/authorization-code).

package/docs/oauth/sample-applications.md

@@ -0,0 +1,199 @@
+# 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. Samples are separated by OAuth client type and platform because confidential and native clients have different credential boundaries.
+
+> [!TIP] Open-source sample
+> [View the confidential Node.js sample on GitHub](https://github.com/lunch-money/lm-oauth-confidential-node-example) or begin with its [README](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/main/README.md).
+
+## Confidential Node.js and TypeScript sample
+
+`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@fbf03343847032ef256994758adf397218d63f74: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='https://api-alpha.lunchmoney.dev/'
+```
+
+The sample uses `LUNCH_MONEY_API_BASE_URL` 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.
+
+> [!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`, 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.
+
+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. Revoke and verify access
+
+Choose **Revoke and verify**.
+
+- 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 **Local reset only** to remove the now-unusable local credential and browser session before starting again.
+
+### Local reset is not revocation
+
+**Local reset only** clears the sample's browser session and locally stored credential. It does not contact Lunch Money and does not revoke active access.
+
+When access is still active, revoke it first through **Revoke and verify** or Lunch Money's Connected Apps page. Use local reset 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/fbf03343847032ef256994758adf397218d63f74/src/oauth/README.md), [security model](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/fbf03343847032ef256994758adf397218d63f74/SECURITY.md), [production checklist](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/fbf03343847032ef256994758adf397218d63f74/PRODUCTION_CHECKLIST.md), and [troubleshooting guide](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/fbf03343847032ef256994758adf397218d63f74/TROUBLESHOOTING.md).
+<!-- END GENERATED OAUTH SAMPLE WALKTHROUGH -->
+
+## Understand and apply the 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.
+
+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 applications
+
+A separate native/public-client sample is planned but is not yet available. Native mobile and desktop applications use PKCE **without a client secret** and store tokens in platform secure storage. Follow the [native application guidance](/oauth/native-apps); do not adapt the confidential sample by placing its client secret or server-held credentials in installed application code.
+
+Next: [Develop and test your OAuth application](/oauth/development) and [operate it securely](/oauth/security).

package/docs/oauth/security.md

@@ -22,6 +22,16 @@ In the browser-based model, the short-lived access token is also visible to the
 
 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.
 
+## 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 the verified credential set under a stable internal application-user ID. If one application user may connect more than one Lunch Money context, also assign each connection its own stable internal connection ID. These identifiers belong to your application; do not use an email address, callback parameter, form field, or any other browser-supplied value as the credential owner.
+
+Enforce the same ownership boundary every time your backend reads credentials, replaces them after authorization or refresh, revokes them, or deletes them. Durable credentials must be encrypted at rest, and backend access should be limited to the services and operators that need it. Never return refresh tokens or client secrets to browser JavaScript.
+
+The [confidential Node.js sample](/oauth/sample-applications#understand-and-apply-the-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
 
 - Generate unpredictable, session-bound, single-use `state` and verify it before exchanging a code.
@@ -37,7 +47,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. 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 logout or 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

@@ -14,9 +14,11 @@ Access tokens are deliberately short-lived. Record when the token response arriv
 
 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.
 
+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.
 
-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 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.
 
 ## Revoke access
 
@@ -55,6 +57,8 @@ 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). Your application should treat the resulting authentication failure as terminal and ask the user to authorize again when they want to reconnect.
+
 ## 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`.
 

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,6 +312,7 @@
         { "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" },

package/package.json

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

package/v2/spec/lunch-money-api-v2.yaml

@@ -42,7 +42,7 @@ info:
   license:
     name: Apache 2.0
     url: http://www.apache.org/licenses/LICENSE-2.0.html
-  version: 2.11.1
+  version: 2.11.2
 
 servers:
   - url: https://api.lunchmoney.dev/v2