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

package/docs/branding-your-app.md

@@ -45,7 +45,7 @@ A few common, low-friction ways to brand an integration:
 
 1. **README or docs** — a short "Built with Lunch Money" line plus the Powered by badge linking to <a href="https://lunchmoney.app/" target="_blank" rel="noopener noreferrer">lunchmoney.app</a>
 2. **App footer or about screen** — the Powered by badge next to your own branding
-3. **Onboarding or connect flow** — official logo when prompting users to authorize or paste an access token
+3. **Onboarding or connect flow** — official logo when asking users to connect their Lunch Money account through OAuth. Applications intended for other users should not ask them to paste a personal access token; see the [OAuth overview](/oauth)
 4. **Community listings** — consistent naming ("My Tool for Lunch Money") so users can find and trust your project
 
 Keep your own product name primary. Lunch Money branding should signal the connection, not compete with your identity.

package/docs/getting-started.md

@@ -27,9 +27,11 @@ Choose the option to "Set up Demo". This will add categories, accounts, tags and
 ![Add Demo Data](/images/DemoData.png)
 :::
 
-## Getting an access token
+## Getting a personal access token
 
-Lunch Money API requests are authenticated using the Bearer Token authentication method. In plain English, this means that you will pass a token associated with your budgeting account to Lunch Money. This is so we know which account to operate on and that the request came from someone who can access that account.
+Lunch Money API requests are authenticated using the Bearer Token authentication method. In plain English, this means that you will pass a personal access token associated with your budgeting account to Lunch Money. This is so we know which account to operate on and that the request came from someone who can access that account.
+
+This guide uses a personal access token so you can explore the API with your own budgeting account. If you are building an application that other people will connect to Lunch Money, start with the [OAuth overview](/oauth) instead.
 
 :::tabs
 
@@ -39,25 +41,25 @@ Navigate to <a href="https://my.lunchmoney.app/developers" target="_blank" rel="
 ![Green Budgets Icon](/images/green_budget.png)
 
 @tab 2. Request Access Token
-In the upper right hand corner of the page, give your access token a label and specify what you are using it for. When you're done, hit the "Request Access Token" button.
+In the upper right hand corner of the page, give your personal access token a label and specify what you are using it for. When you're done, hit the "Request Access Token" button.
 ![Request Token](/images/RequestAccessToken.png)
 
 @tab 3. Save Access Token
-After you do this, the web page will show you a long alphanumeric string. This is your access token. Hit the copy button and save this token somewhere safe. It is only shown to you when you create it.
+After you do this, the web page will show you a long alphanumeric string. This is your personal access token. Hit the copy button and save this token somewhere safe. It is only shown to you when you create it.
 :::
 
-Congratulations! You've got an access token and are ready to make an API request! Later, when you are more comfortable with the API, you can repeat this process to create a new access token associated with your real budget.
+Congratulations! You've got a personal access token and are ready to make an API request! Later, when you are more comfortable with the API, you can repeat this process to create a new personal access token associated with your real budget.
 
 > [!WARNING]
-> Treat your access tokens like passwords. Don't share them with anyone you don't trust.
+> Treat your personal access tokens like passwords. Don't share them with anyone you don't trust.
 
-If you ever worry that your access token has been compromised, you can always come back to the Developers page and hit the Revoke button.
+If you ever worry that your personal access token has been compromised, you can always come back to the Developers page and hit the Revoke button.
 
 > [!NOTE]
-> Give your access tokens descriptive names so you can easily identify and revoke them later if needed.
+> Give your personal access tokens descriptive names so you can easily identify and revoke them later if needed.
 
 
-## Using your access token
+## Using your personal access token
 
 When you start to write code that makes API calls, you will need to include this token in each request using an Authorization header. Here is an example curl request:
 
@@ -68,7 +70,7 @@ curl --location 'https://api.lunchmoney.dev/v2/me' \
 
 If this doesn't make sense yet, that's OK!
 
-There is an easier way to use your access token to make requests. Head over to the [API Reference Documentation](/v2/docs).
+There is an easier way to use your personal access token to make requests. Head over to the [API Reference Documentation](/v2/docs).
 
 :::tabs
 
@@ -85,6 +87,8 @@ This will pop up a dialog box that you can use to send an API request. This is a
 
 From here, you can explore the rest of the Lunch Money API and start thinking about what you might do with it.
 
+When you are ready to build an application that other Lunch Money users can connect to, [learn how OAuth grants access without asking users to share personal access tokens](/oauth).
+
 ## What can you build?
 
 The Lunch Money community has already built a wide variety of tools — automations, importers, dashboards, and more. Check out the <a href="https://lunchmoney.app/developers#community-projects" target="_blank" rel="noopener noreferrer">Developer Tools & Community Projects</a> list for inspiration, or drop by the <a href="https://discord.com/channels/842337014556262411/1134597088504729780" target="_blank" rel="noopener noreferrer">Show and Tell channel</a> on Discord to see what others are sharing.

package/docs/introduction.md

@@ -10,7 +10,7 @@ The v2 API is available at:
 https://api.lunchmoney.dev/v2
 ```
 
-Get your access token from the <a href="https://my.lunchmoney.app/developers" target="_blank" rel="noopener noreferrer">Lunch Money app developers page</a> and include it as a Bearer token in every request:
+To explore the API or work with your own budgeting account, create a personal access token on the <a href="https://my.lunchmoney.app/developers" target="_blank" rel="noopener noreferrer">Developers page</a>. If you are building an application for other Lunch Money users, [use OAuth](/oauth) instead. Both kinds of access token are sent as a Bearer token with each request:
 
 ```http
 Authorization: Bearer YOUR_ACCESS_TOKEN
@@ -59,5 +59,6 @@ Join the conversation in the <a href="https://lunchmoney.app/discord" target="_b
 **Useful links:**
 - <a href="/v2/docs">Interactive API Reference</a>
 - [Getting started guide](/getting-started)
+- [OAuth overview](/oauth)
 - <a href="https://github.com/lunch-money/awesome-lunchmoney" target="_blank" rel="noopener noreferrer">Awesome Lunch Money Projects</a>
 - [Contact: devsupport@lunchmoney.app](mailto:devsupport@lunchmoney.app)

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

@@ -6,23 +6,23 @@ OAuth lets your application access Lunch Money on behalf of a user without askin
 
 ## Choose OAuth or a personal access token
 
-| Question | Personal access token | OAuth application and client |
+| Question | Personal access token | OAuth client |
 | --- | --- | --- |
 | Whose data can it access? | One budgeting account belonging to the user who created the token | One budgeting account selected by each user who authorizes the application |
 | Best fit | API exploration, one-off scripts, and short-lived work on your own account | Persistent integrations and applications intended for other users |
 | How is access granted? | The user creates a token on the [Developers page](https://my.lunchmoney.app/developers) in the Lunch Money web app | The user signs in and approves the permissions requested by the application |
 | Credential handling | The user keeps the token and sends it with their own API requests; third-party applications should use OAuth instead of asking users to share one | The authorization flow delivers application-specific tokens without asking for a personal token |
-| Permissions | Full access to the Lunch Money APIs available for that budgeting account, with no fine-grained permission controls | Only the permissions selected when the application was created |
+| Permissions | Full access to the Lunch Money APIs available for that budgeting account, with no fine-grained permission controls | Only the permissions selected when the OAuth client was registered |
 | Lifecycle | Created and revoked by the user | Short-lived access tokens and optional finite refresh access; the user can revoke the application's access |
 
 Personal access tokens remain useful for quick work on your own account. OAuth is the recommended model for applications and integrations that other Lunch Money users will connect to, as well as automations that need to run over time.
 
 ## What limits access
 
-When a developer creates an OAuth application, they select the scopes—the specific permissions—the application needs. Later, when a Lunch Money user authorizes the application, Lunch Money shows them that complete permission set before they approve access. Choose only the permissions the application's features require. A focused permission request is easier for users to understand and trust, and reduces the risk of the application reading or changing data it does not need.
+An OAuth client is an application's registration with Lunch Money. When a developer registers the client, they select the scopes—the specific permissions—the application needs. Later, when a Lunch Money user authorizes the application, Lunch Money shows them that complete permission set before they approve access. Choose only the permissions the application's features require. A focused permission request is easier for users to understand and trust, and reduces the risk of the application reading or changing data it does not need.
 
 ## Before you start
 
-You need an active Lunch Money account to [register and manage an OAuth application](/oauth/applications). During development, only the application owner can authorize it. Approval is required before other Lunch Money users can authorize it.
+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/native-apps.md

@@ -13,9 +13,9 @@ Use Lunch Money's authorization-server discovery document and configure `token_e
 
 ## Redirects
 
-Use a redirect mechanism that returns control to your app and that your platform can bind to it. Claimed Universal Links or Android App Links provide stronger app ownership than a custom URI scheme when correctly configured. Custom schemes must be distinctive and protected against interception.
+Use a redirect mechanism that returns control to your app and that your platform can bind to it. Claimed Universal Links or Android App Links provide stronger app ownership than a custom URI scheme when correctly configured. A private-use scheme must contain a dot, such as `app.example.demo:/oauth/callback`, and must be protected against interception.
 
-The loopback callbacks supported for confidential web development do not define native or desktop redirect support. Follow the native redirect choices accepted during client registration; do not assume the confidential web-client loopback rules apply.
+Native clients may use an HTTP loopback redirect with `localhost`, `127.0.0.1`, or `[::1]`. The scheme, host, path, and query string must exactly match the registered URI, but the port may differ so the application can bind an ephemeral port at runtime. The exception applies only to loopback redirects for native clients; native HTTPS and private-use scheme redirects must match every component of the registered URI exactly.
 
 ## Store and renew tokens
 

package/docs/oauth/oauth-scope-catalog-design.md

@@ -45,9 +45,9 @@ This proposal makes these additional decisions:
 - Map non-CRUD mutations by effect: Plaid and synced-crypto refresh operations
   use `:update`; transaction split/group and their reversals use
   `transactions:update`; balance-history and budget upserts use `:update`.
-- Let `transactions:read` expose attachment IDs and metadata, while requiring
-  explicit `transaction_attachments:*` scopes to download, attach, or delete
-  files.
+- Keep attachment metadata and download access behind
+  `transaction_attachments:read`. The other `transaction_attachments:*` scopes
+  separately authorize attaching or deleting files.
 
 ## Package direction
 

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.
@@ -28,17 +30,18 @@ The client type cannot be changed after registration. See [OAuth concepts](/oaut
 
 A redirect URI tells Lunch Money where to return the user after authorization. Register every callback address your application will use. Confidential web clients must match every component of a registered URI, including its scheme, host, port, path, and query string. Native-client loopback redirects use the same exact matching except that the ephemeral port is ignored.
 
-Web applications normally use an HTTPS callback. If you need a callback for local development, review the [loopback guidance](/oauth/development#local-loopback-callbacks) before registering one. Mobile and desktop applications may use an app-specific URL scheme or verified HTTPS link accepted by the Developer Portal.
+Web applications normally use an HTTPS callback. If you need a callback for local development, review the [loopback guidance](/oauth/development#local-loopback-callbacks) before registering one. Mobile and desktop applications may use a private-use scheme containing a dot, such as `app.example.demo:/oauth/callback`, or a verified HTTPS link accepted by the Developer Portal.
 
 ## Register the OAuth client
 
 Open the [new OAuth client form](/oauth/applications/new) in the Developer Portal. Then:
 
 1. Describe the application so Lunch Money users can understand who built it and what it does.
-2. Choose its client type.
-3. Add at least one redirect URI.
-4. Select the planned scopes.
-5. Accept the current Lunch Money API Terms of Use and select **Register OAuth client**.
+2. Provide a monitored support email where users can reach you if authorization fails.
+3. Choose its client type.
+4. Add at least one redirect URI.
+5. Select the planned scopes.
+6. Accept the current Lunch Money API Terms of Use and select **Register OAuth client**.
 
 After registration, record the client ID in your application configuration. A client ID identifies the registration but is not a secret.
 
@@ -48,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/review-and-approval.md

@@ -18,23 +18,35 @@ Deleted clients disappear from the owner's Developer Portal.
 
 ## Prepare for review
 
-Submitting a client for review is how you make your application authorizable by Lunch Money users other than yourself. You can create and test a client with only basic information, but review requires a complete, user-facing application profile and production-ready configuration.
+Submitting a client for review is how you make your application authorizable by Lunch Money users other than yourself. Registration already requires basic information, including a support email, but review requires a complete, user-facing application profile and production-ready configuration.
 
-Before requesting review, provide:
+Before requesting review, make sure the client has:
 
 - an application description, developer name, and logo so users can identify the application and who created it;
 - a monitored support email where users and Lunch Money can reach you;
 - a publicly accessible homepage URL where users can learn about the application;
 - a publicly accessible privacy policy URL explaining how the application handles user data;
-- at least one eligible production HTTPS redirect URI;
+- at least one eligible redirect URI—a confidential web client needs a non-loopback production HTTPS redirect, while a native client may use a private-use scheme or loopback redirect;
 - a recognized, supported scope set and an explanation of why the application needs each permission; and
 - acceptance of the current Lunch Money API Terms of Use.
 
+The privacy policy must be available at a direct, stable public URL and explain how the application collects, uses, stores, shares, and deletes user data. A published privacy-policy page in a public source-code repository can satisfy this requirement. An in-app page that requires installation or sign-in, or a link to source code without a clear privacy policy, does not.
+
 Fully test the client before submission. A confidential web client also needs at least one active, non-expired secret; a native or public client does not.
 
 Explain which features use each requested permission, how that access benefits users, and why narrower scopes are insufficient. If the client includes `offline_access`, explain why the integration must operate while the user is absent. You may also provide documentation, source-code, and demonstration URLs or context about changes made after earlier feedback.
 
-A client may retain owner-only loopback callbacks alongside its production HTTPS callback, but a loopback-only client is not ready for review.
+Open-source applications are welcome. If your source code is public, include the repository URL in the review request's additional context. It can help the reviewer understand how your application uses Lunch Money data and the permissions it requests. Publishing source code is optional and is not required for approval.
+
+A confidential web client may retain owner-only loopback callbacks alongside its production HTTPS callback, but it still needs a non-loopback production HTTPS redirect before review.
+
+### Native applications
+
+You do not need to create a standalone marketing website for a native application. Its public Apple App Store or Google Play listing can serve as the homepage if it clearly explains what the application does and identifies the developer. A public pre-release listing, project page, or README in a public source-code repository can also work.
+
+If you provide a pre-release listing or beta-testing link, use the review request's additional context to explain how to access it. Include any required opt-in steps, supported platforms or devices, and other information the reviewer needs to evaluate the application. Do not include passwords, client secrets, tokens, or other credentials.
+
+Native clients may be reviewed with loopback or private-use scheme redirects.
 
 ## Submit, cancel, or revise
 

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/scopes.md

@@ -71,11 +71,11 @@ View and manage all supported Lunch Money data
 | <a id="scope-manual-accounts-delete"></a>`manual_accounts:delete` | Delete manually managed accounts | `deleteManualAccount` |
 | <a id="scope-plaid-accounts-read"></a>`plaid_accounts:read` | View accounts connected through Plaid | `getAllPlaidAccounts`, `getPlaidAccountById` |
 | <a id="scope-plaid-accounts-update"></a>`plaid_accounts:update` | Request a Plaid account refresh, which may import new transactions | `triggerPlaidAccountFetch` |
-| <a id="scope-transactions-read"></a>`transactions:read` | View transactions, including split and group information and attachment metadata | `getAllTransactions`, `getTransactionById` |
+| <a id="scope-transactions-read"></a>`transactions:read` | View transactions, including split and group information | `getAllTransactions`, `getTransactionById` |
 | <a id="scope-transactions-create"></a>`transactions:create` | Create transactions | `createNewTransactions` |
 | <a id="scope-transactions-update"></a>`transactions:update` | Update, split, unsplit, group, and ungroup transactions | `updateTransactions`, `updateTransaction`, `groupTransactions`, `ungroupTransactions`, `splitTransaction`, `unsplitTransaction` |
 | <a id="scope-transactions-delete"></a>`transactions:delete` | Delete transactions | `deleteTransactions`, `deleteTransactionById` |
-| <a id="scope-transaction-attachments-read"></a>`transaction_attachments:read` | Get download access to transaction attachments | `getTransactionAttachmentUrl` |
+| <a id="scope-transaction-attachments-read"></a>`transaction_attachments:read` | View transaction attachment metadata and get download access to attachments | `getTransactionAttachmentUrl` |
 | <a id="scope-transaction-attachments-create"></a>`transaction_attachments:create` | Attach files to transactions | `attachFileToTransaction` |
 | <a id="scope-transaction-attachments-delete"></a>`transaction_attachments:delete` | Delete transaction attachments | `deleteTransactionAttachment` |
 | <a id="scope-tags-read"></a>`tags:read` | View tags | `getAllTags`, `getTagById` |

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`.
 
@@ -29,11 +31,24 @@ Match on `error` when it is returned, verify `state`, and treat `error_descripti
 | `invalid_scope` | The client does not have a usable registered scope set | Open the client in the [Developer Portal](/oauth/applications) and review its assigned scopes. Registered clients always use that complete set. |
 | `access_denied` | The user declined or the application is unavailable to that user | Treat denial normally. During development, only the owner may authorize; other users require an active approved application. |
 
-### Redirect URI mismatch
+### Users cannot authorize an unapproved client
+
+Until a client is approved, only its owner may authorize the application. Anyone else is stopped at the consent screen and is never returned to your application, so you will see no callback and no `error` parameter for these attempts.
+
+Those users are shown the support email registered with your client so they can reach you. If you did not expect authorization to be unavailable, check the client in the [Developer Portal](/oauth/applications). A client stays in development until it is submitted for review and approved. A rejected or disabled client also prevents other users from authorizing the application.
+
+### Redirect URI problems
 
-If the redirect URI does not exactly match one registered for the client, Lunch Money cannot safely return the browser to it. Instead, Lunch Money shows an error page explaining that it could not return the user to the application. The page displays `REDIRECT_URI_MISMATCH`, a request or reference ID, a timestamp, and the application name and public client ID when they are available.
+If the callback address cannot be matched to one registered for the client, Lunch Money cannot safely return the browser to your application. It stops locally and shows the user a page explaining what happened, rather than redirecting with an `error`. Your application receives no callback for these attempts.
+
+The page displays one of two codes, a UTC timestamp, and the application name and public client ID once the client has been resolved.
+
+| Code | Likely cause | What to do |
+| --- | --- | --- |
+| `redirect_uri_mismatch` | The address your application sent is not registered for the client, or differs from a registered one | Open the client in the [Developer Portal](/oauth/applications) and compare the address with its registered redirect URIs. Web-client redirects and native HTTPS or private-use scheme redirects must match every component exactly. For a native HTTP loopback redirect, the scheme, host, path, and query string must match, but the ephemeral port may differ. See [local callback failures](#local-callback-failures). |
+| `redirect_uri_missing` | No `redirect_uri` was sent, and the client has more than one registered, so Lunch Money cannot choose | Send the parameter explicitly. A client with exactly one registered address may omit it; Lunch Money then uses the registered value. |
 
-Ask the user to report those displayed details—not the complete attempted URL, credentials, authorization codes, tokens, cookies, or PKCE values. Open the client in the [Developer Portal](/oauth/applications), find its registered redirect URIs, and compare the complete URL with the value your application sent. The two values must be identical.
+The page offers the user a prefilled message addressed to the support email registered with your client. It contains the error code, the timestamp, the application name and client ID, and the callback address your application sent, reduced to its origin and path with any query string removed. Compare that sanitized callback address with the redirect URIs registered for the client, then correct either the registered URI or the address your application sends.
 
 ## Callback validation failures
 

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.1-preview.9",
+  "version": "2.11.2-preview.2",
   "description": "Developer documentation content for Lunch Money APIs",
   "exports": {
     ".": "./package.json",

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
 ```
 
-Get your access token from the <a href="https://my.lunchmoney.app/developers" target="_blank" rel="noopener noreferrer">Lunch Money Developers page</a>. See the [Getting started guide](/getting-started) for a step-by-step walkthrough including how to create a test budget.
+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).
 
 ## Base URL
 

package/v2/docs/version-history.md

@@ -5,9 +5,12 @@ The Lunch Money API spec uses a modified version of SEMVER for its versioning me
 - The minor version represents the number of main endpoints the current version of the spec supports.  For example, a version of the API that supports the /me, /categories, and /transactions endpoints would have a minor version of 3.
 - The revision number represents the number of updates since the last endpoint was added.  For example, each time changes are made to one of the existing three APIs as described above, the revision number will be bumped.
 
+## 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 the OAuth 2.0 authorization-code flow used to obtain access tokens
+
 ## v2.11.1 - TBD
-- Add the OAuth scope and scope-group catalog mapped to V2 `operationId` values
-- Document OAuth 2.0 authorization-code endpoints and required OAuth scopes for every V2 operation
 - 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

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

@@ -4,9 +4,9 @@ info:
   description: |-
     ### Introduction
 
-    Welcome to the Lunch Money v2 API reference. This is the **v2.11.1** spec.
+    Welcome to the Lunch Money v2 API reference. This is the **v2.11.2** spec.
 
-    The API is available at `https://api.lunchmoney.dev/v2`. Get your access token from the [Lunch Money developers page](https://my.lunchmoney.app/developers).
+    The API is available at `https://api.lunchmoney.dev/v2`. Use a personal access token from the [Lunch Money Developers page](https://my.lunchmoney.app/developers) for API exploration or work with your own budgeting account. Applications built for other Lunch Money users should use an [OAuth access token issued after the user authorizes the application](https://lunchmoney.dev/oauth).
 
     
     **Try it from these docs**
@@ -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
@@ -2712,8 +2712,11 @@ components:
           type: array
           nullable: false
           description: A list of objects that describe any attachments to the
-            transaction. This is only present when the `include_files` query
-            parameter is set to true.
+            transaction. For OAuth clients, this property is available only
+            with the `transaction_attachments:read` scope. Without that scope,
+            an absent `files` property does not mean the transaction has no
+            attachments. See the operation description for its attachment
+            behavior.
           items:
             $ref: "#/components/schemas/transactionAttachmentObject"
         source:
@@ -3008,7 +3011,10 @@ components:
           type: array
           nullable: false
           description: A list of objects that describe any attachments to the
-            transaction
+            transaction. OAuth clients also need the
+            `transaction_attachments:read` scope. Without it, this property is
+            omitted rather than returned as an empty array, so an absent
+            `files` property does not mean the transaction has no attachments.
           items:
             $ref: "#/components/schemas/transactionAttachmentObject"
       required:
@@ -5136,11 +5142,11 @@ components:
             manual_accounts:delete: "Delete manually managed accounts"
             plaid_accounts:read: "View accounts connected through Plaid"
             plaid_accounts:update: "Request a Plaid account refresh, which may import new transactions"
-            transactions:read: "View transactions, including split and group information and attachment metadata"
+            transactions:read: "View transactions, including split and group information"
             transactions:create: "Create transactions"
             transactions:update: "Update, split, unsplit, group, and ungroup transactions"
             transactions:delete: "Delete transactions"
-            transaction_attachments:read: "Get download access to transaction attachments"
+            transaction_attachments:read: "View transaction attachment metadata and get download access to attachments"
             transaction_attachments:create: "Attach files to transactions"
             transaction_attachments:delete: "Delete transaction attachments"
             tags:read: "View tags"
@@ -9667,6 +9673,9 @@ paths:
           description: By default, the `files` property is not included in the
             response. Set to true if you'd like the responses to include a list
             of objects that describe any files attached to the transactions.
+            OAuth clients must have both `transactions:read` and
+            `transaction_attachments:read`; otherwise the request returns a
+            `403` `insufficient_scope` error.
         - name: limit
           in: query
           schema:
@@ -9950,7 +9959,10 @@ paths:
         successfully inserted.<br>
         - `skipped_duplicates`: A list of
         transactions that were duplicates of existing transactions and were not
-        inserted.
+        inserted.<p>
+
+        For OAuth clients, returned transactions include the `files` property
+        only when the client has the `transaction_attachments:read` scope.
       operationId: createNewTransactions
       security:
         - bearerSecurity: []
@@ -10394,7 +10406,10 @@ paths:
 
         Each transaction in the array **must** include an `id` property to identify which transaction to update, along with at least one other property to be updated. For example, a transaction object that contains only an `id` and `category_id` property is valid.<br><br>
         
-        The request can include between 1 and 500 transactions to update in a single call.
+        The request can include between 1 and 500 transactions to update in a single call.<br><br>
+
+        For OAuth clients, returned transactions include the `files` property
+        only when the client has the `transaction_attachments:read` scope.
       operationId: updateTransactions
       security:
         - bearerSecurity: []
@@ -10877,7 +10892,8 @@ paths:
         added to transactions that were inserted or updated via the API.
 
         - `files` will be a list of objects that describe any attachments to the
-        transaction.
+        transaction. For OAuth clients, this property is included only when the
+        client has the `transaction_attachments:read` scope.
 
 
         If `is_group_parent` is true in the returned transaction, the object will also
@@ -11132,7 +11148,11 @@ paths:
         It is also possible to provide only the properties to be updated in the
         request body, as long as the request includes at least one of the
         properties that is not listed above. For example a request body that contains only
-        an `category_id` attribute is valid.
+        an `category_id` attribute is valid.<br><br>
+
+        For OAuth clients, the returned transaction includes the `files`
+        property only when the client has the
+        `transaction_attachments:read` scope.
         
       operationId: updateTransaction
       security:
@@ -11348,7 +11368,11 @@ paths:
         transaction. The grouped transactions will
 
         be included in the `children` property of the transaction returned in
-        the response
+        the response.<br><br>
+
+        For OAuth clients, the returned group and its children include the
+        `files` property only when the client has the
+        `transaction_attachments:read` scope.
       operationId: groupTransactions
       security:
         - bearerSecurity: []
@@ -11701,7 +11725,11 @@ paths:
 
         To see the details of the original parent transaction after it has been
         split, use the `GET /transactions/{id}` endpoint and pass the value of
-        the `split_parent_id` of one of the children.
+        the `split_parent_id` of one of the children.<br><br>
+
+        For OAuth clients, the returned parent and its children include the
+        `files` property only when the client has the
+        `transaction_attachments:read` scope.
       operationId: splitTransaction
       security:
         - bearerSecurity: []