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

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

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

@@ -28,17 +28,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.
 

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

@@ -29,11 +29,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
 
-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.
+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.
 
-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.
+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 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. |
+
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunch-money/developer-docs",
-  "version": "2.11.1-preview.9",
+  "version": "2.11.2-preview.1",
   "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**
@@ -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: []