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

package/docs/oauth/authorization-code.md

@@ -75,7 +75,7 @@ Host: api.lunchmoney.dev
 Authorization: Bearer YOUR_ACCESS_TOKEN
 ```
 
-The operation must be allowed by the token's scope and by the user's access to the selected budget account. See the [scope catalog](/oauth/scopes).
+The operation must be allowed by the token's scope and by the user's access to the selected budget account. See [OAuth scopes](/oauth/scopes).
 
 Call `GET /v2/me` immediately after the token exchange, before normal credential persistence. It requires `me:read`. Strictly validate the response: `id` identifies the Lunch Money user, `account_id` identifies the selected budget account, and `budget_name` is its display name. When reconnecting, use this response to establish the account identity rather than assuming the user selected the same budget. See [users, budget accounts, and access tokens](/oauth/concepts#users-budget-accounts-and-access-tokens).
 

package/docs/oauth/concepts.md

@@ -14,7 +14,7 @@ These terms describe who participates in Lunch Money OAuth and what each credent
 
 A **Lunch Money user** is the person who signs in to Lunch Money. One user can have access to multiple **budget accounts**, such as a personal budget, a household budget, and a test budget. Each budget account contains its own financial data. Here, “budget account” means that collection of data, not an individual bank or manually managed account within it.
 
-During OAuth authorization, the user selects one budget account and approves your client's permissions. The resulting **OAuth access token is specific to that Lunch Money user and budget account pair**, for your client. It does not grant access to every budget account the user can access.
+During OAuth authorization, the user selects one budget account and approves your client's scopes. The resulting **OAuth access token is specific to that Lunch Money user and budget account pair**, for your client. It does not grant access to every budget account the user can access.
 
 For example, Alex can access both “Household” and “API testing.” If Alex selects “API testing” during authorization, your application's access token operates on that budget account. It cannot use the same token to read or update “Household.” Scopes determine which operations the application may perform within the selected account; they do not add access to other budget accounts.
 
@@ -84,9 +84,9 @@ The developer registers each permitted redirect URI in advance. For a confidenti
 
 ## Scopes and least privilege
 
-Resource scopes such as `transactions:read` authorize specific ways of working with Lunch Money data. A scope generally applies to a particular kind of action—such as reading or updating a resource—and only to the relevant API endpoints. Permissions are independent: for example, `transactions:update` does not also grant `transactions:read`.
+Scopes are named permissions that define what an OAuth client may do with Lunch Money data. Resource scopes such as `transactions:read` authorize a particular kind of action—such as reading or updating a resource—and only for the relevant API endpoints. Scopes are independent: for example, `transactions:update` does not also grant `transactions:read`.
 
-The [V2 API reference](/v2/docs) identifies the scope required by each API endpoint. Use it together with the [scope catalog](/oauth/scopes) to select the permissions your application's features require.
+The [V2 API reference](/v2/docs) identifies the OAuth scope requirements for each operation. An operation may require one scope, several scopes together, or additional scopes when a request enables broader behavior. Review the operation and relevant parameter descriptions, then use the [OAuth scopes](/oauth/scopes) page to select the scopes your application's features require.
 
 Scopes are selected when the client is created and cannot be edited later. Every user who authorizes that client sees and grants all—and only—the scopes the developer selected. To change them, create and test a replacement client, complete review when applicable, update your integration, and ask existing users to authorize again. Existing authorizations and tokens do not move to the replacement client.
 

package/docs/oauth/development.md

@@ -45,7 +45,7 @@ Test with one Lunch Money user authorizing multiple budget accounts, then with a
 1. Complete authorization. For each attempt, your application should create a random `state` value, save it with the application user's session, and verify that Lunch Money returns the same value to the callback. Rejecting a missing, changed, or reused value prevents a callback started elsewhere from being attached to the wrong session.
 2. Keep the PKCE verifier with that same authorization attempt and use it when exchanging the returned code. Confirm that an exchange with a missing or changed verifier fails; this prevents someone who intercepts the code from using it.
 3. Read the token response's `scope` field and confirm that it contains the complete scope set registered for the client. Do not inspect or parse the access token itself.
-4. Call every scope-dependent feature, including negative permission cases.
+4. Call every scope-dependent feature, including insufficient-scope cases.
 5. Test user denial, missing or changed `state`, callback errors, and interrupted authorization attempts. Confirm that denial or a failed `/v2/me` validation leaves all existing connections unchanged.
 6. Make `GET /v2/me` fail or return an invalid shape after a successful exchange. Confirm that the application saves no unidentified or partial connection.
 7. Reauthorize an already connected Lunch Money user/account pair. Confirm that the application atomically replaces that connection's credentials, makes it active, and does not create a duplicate.

package/docs/oauth/index.md

@@ -2,7 +2,7 @@
 
 OAuth lets your application access Lunch Money on behalf of a user without asking that person to copy and share a personal access token. **If you are building an application for anyone other than yourself, use OAuth.** It gives each user a familiar Lunch Money sign-in and consent experience while keeping their personal access token out of your application.
 
-![OAuth authorization-code flow across your application, the Lunch Money user, and Lunch Money. The application redirects the user's browser, Lunch Money handles sign-in and presents the budget-account and permission choices, the user approves access, Lunch Money returns an authorization code, and the application exchanges it for tokens, calls GET /v2/me, saves the identified connection, and calls the API for that account.](/v2/images/oauth-authorization-flow.svg)
+![OAuth authorization-code flow across your application, the Lunch Money user, and Lunch Money. The application redirects the user's browser, Lunch Money handles sign-in and presents the budget-account and scope choices, the user approves access, Lunch Money returns an authorization code, and the application exchanges it for tokens, calls GET /v2/me, saves the identified connection, and calls the API for that account.](/v2/images/oauth-authorization-flow.svg)
 
 ## Choose OAuth or a personal access token
 
@@ -10,16 +10,16 @@ OAuth lets your application access Lunch Money on behalf of a user without askin
 | --- | --- | --- |
 | Whose data can it access? | One budget account belonging to the user who created the token | One budget 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 |
+| 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 scopes 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 budget account, with no fine-grained permission controls | Only the permissions selected when the OAuth client was registered |
+| Scopes | Full access to the Lunch Money APIs available for that budget account, with no fine-grained scope controls | Only the scopes 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
 
-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.
+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 scope set before they approve access. Choose only the scopes the application's features require. A focused scope request is easier for users to understand and trust, and reduces the risk of the application reading or changing data it does not need.
 
 One Lunch Money user can have multiple budget accounts and multiple connections to the same OAuth client. Each OAuth access token represents that user and the single budget account they selected during authorization. It does not provide access to all of their budgets. Read [users, budget accounts, and access tokens](/oauth/concepts#users-budget-accounts-and-access-tokens) for an example and how to identify the connected account.
 
@@ -27,4 +27,4 @@ One Lunch Money user can have multiple budget accounts and multiple connections
 
 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). 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.
+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 [OAuth scopes](/oauth/scopes) to plan the client's scopes and [troubleshooting](/oauth/troubleshooting) when a flow fails.

package/docs/oauth/register-client.md

@@ -1,19 +1,19 @@
 # Register an OAuth client
 
-Before you add OAuth to your application code, register an OAuth client with Lunch Money. The client identifies your application during authorization and tells Lunch Money who is requesting access, where to return the user, and which permissions the application needs.
+Before you add OAuth to your application code, register an OAuth client with Lunch Money. The client identifies your application during authorization and tells Lunch Money who is requesting access, where to return the user, and which scopes the application needs.
 
 [Register a new OAuth client](/oauth/applications/new) in the Developer Portal when you are ready to begin.
 
 > [!NOTE] Development access is owner-only
 > A newly registered client starts in development. Only the Lunch Money user who owns it can authorize it until the client has been reviewed and approved.
 
-## Plan the permissions
+## Plan the scopes
 
-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.
+List the Lunch Money features your application will provide, then use the [OAuth scopes](/oauth/scopes) page to choose the smallest complete set of scopes those features require. Select `offline_access` only if the application needs to continue making API requests after the initial access token expires and while the user is away.
 
 If your application may support more than one Lunch Money user or budget account, always include `me:read`. After authorization, `GET /v2/me` lets your application record both the Lunch Money user's `id` and the selected budget account's `account_id`, then store the connection under the complete application-owner and Lunch Money user/account identity. The same scope is also required when your application only needs to identify one connected budget account.
 
-Scopes cannot be changed after registration. While you are developing your application, creating a replacement client is inexpensive, so let the scope set evolve as you learn what the application needs. Aim to have the application's core functionality—and its required permissions—settled before you submit the client for review.
+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 scopes—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.
 

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

@@ -2,7 +2,7 @@
 
 Every new OAuth client starts in development, where only its owner can authorize it. This gives you time to build and test the application without making an unfinished integration available to other Lunch Money users.
 
-When the application is ready, submit its client for review in the Developer Portal. A Lunch Money employee reviews the application information, requested permissions, redirect configuration, and other readiness requirements. Approval moves the client to `active`, allowing other Lunch Money users to authorize the application.
+When the application is ready, submit its client for review in the Developer Portal. A Lunch Money employee reviews the application information, requested scopes, redirect configuration, and other readiness requirements. Approval moves the client to `active`, allowing other Lunch Money users to authorize the application.
 
 ## Lifecycle states
 
@@ -27,16 +27,16 @@ Before requesting review, make sure the client has:
 - 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 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
+- a recognized, supported scope set and an explanation of why the application needs each scope; 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.
+Explain which features use each requested scope, 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.
 
-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.
+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 scopes 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.
 

package/docs/oauth/scopes.md

@@ -1,13 +1,13 @@
 # OAuth scopes
 
-Choose the smallest complete set of permissions your application needs. This page is generated from the published `@lunch-money/v2-api-spec/oauth-scopes` catalog; do not edit it by hand.
+Scopes are named permissions that define what an OAuth client may do with Lunch Money data. Choose the smallest complete set of scopes your application needs. This page is generated from the published `@lunch-money/v2-api-spec/oauth-scopes` catalog; do not edit it by hand.
 
 > [!NOTE] Scopes are fixed when you create a client
-> Authorization requests omit `scope`. To change permissions later, create and review a replacement client, update your integration, and ask every user to authorize it.
+> Authorization requests omit `scope`. To change scopes later, create and review a replacement client, update your integration, and ask every user to authorize it.
 
 ## Scope groups
 
-Groups are selection shortcuts, not extra permissions. Every predefined group includes `me:read` so an application can identify the authorized Lunch Money user and budget account. A group expands to the exact scopes listed below.
+Groups are selection shortcuts, not additional scopes. Every predefined group includes `me:read` so an application can identify the authorized Lunch Money user and budget account. A group expands to the exact scopes listed below.
 
 ### Read only
 

package/docs/oauth/troubleshooting.md

@@ -129,7 +129,7 @@ WWW-Authenticate: Bearer error="insufficient_scope", scope="transactions:read"
 }
 ```
 
-The `scope` parameter names every scope the endpoint requires, including any the client may already have. It is not a list of only the missing scopes. Check the operation in the [V2 API reference](/v2/docs) or the [scope catalog](/oauth/scopes) to confirm its requirements.
+The `scope` parameter names every scope the endpoint requires, including any the client may already have. It is not a list of only the missing scopes. Check the operation in the [V2 API reference](/v2/docs) or [OAuth scopes](/oauth/scopes) to confirm its requirements.
 
 ### Replace a client to change scopes
 

package/manifest.json

@@ -319,7 +319,7 @@
         { "label": "Troubleshooting", "path": "/oauth/troubleshooting" },
         { "label": "Review and Approval", "path": "/oauth/review-and-approval" },
         { "label": "Native Apps", "path": "/oauth/native-apps" },
-        { "label": "Scope Catalog", "path": "/oauth/scopes" }
+        { "label": "Scopes", "path": "/oauth/scopes" }
       ]},
       { "section": "REFERENCE", "items": [
         { "label": "v2 API Overview", "path": "/v2/overview" },

package/package.json

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

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

@@ -1,6 +1,6 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="1120" height="960" viewBox="0 0 1120 960" role="img" aria-labelledby="title desc">
   <title id="title">Lunch Money OAuth authorization-code flow</title>
-  <desc id="desc">A sequence diagram with three actors: your application, the Lunch Money user, and Lunch Money. The application redirects the user's browser to Lunch Money. When necessary, Lunch Money presents its sign-in screen and the user signs in directly with Lunch Money. Lunch Money then presents the budget-account selector and requested permissions, the user selects an account and approves access, Lunch Money returns an authorization code, and the application exchanges it for tokens. The application calls GET /v2/me, saves the identified connection, and calls the API for that account.</desc>
+  <desc id="desc">A sequence diagram with three actors: your application, the Lunch Money user, and Lunch Money. The application redirects the user's browser to Lunch Money. When necessary, Lunch Money presents its sign-in screen and the user signs in directly with Lunch Money. Lunch Money then presents the budget-account selector and requested scopes, the user selects an account and approves access, Lunch Money returns an authorization code, and the application exchanges it for tokens. The application calls GET /v2/me, saves the identified connection, and calls the API for that account.</desc>
   <defs>
     <marker id="app-arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#b45309"/></marker>
     <marker id="user-arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#9a6700"/></marker>
@@ -23,7 +23,7 @@
   <path class="flow user-flow" d="M560 200 H940"/><rect class="step-bg" x="652" y="178" width="196" height="28" rx="6"/><text class="step" x="750" y="197" text-anchor="middle">2. Request authorization</text>
   <path class="flow lm-flow" d="M950 260 H570"/><rect class="step-bg" x="640" y="238" width="240" height="28" rx="6"/><text class="step" x="760" y="257" text-anchor="middle">3. Show sign-in, when needed</text>
   <path class="flow user-flow" d="M560 320 H940"/><rect class="step-bg" x="605" y="298" width="290" height="28" rx="6"/><text class="step" x="750" y="317" text-anchor="middle">4. Sign in directly with Lunch Money</text>
-  <path class="flow lm-flow" d="M950 380 H570"/><rect class="step-bg" x="545" y="358" width="430" height="28" rx="6"/><text class="step" x="760" y="377" text-anchor="middle">5. Present budget-account selector and permissions</text>
+  <path class="flow lm-flow" d="M950 380 H570"/><rect class="step-bg" x="545" y="358" width="430" height="28" rx="6"/><text class="step" x="760" y="377" text-anchor="middle">5. Present budget-account selector and scopes</text>
   <path class="flow user-flow" d="M560 440 H940"/><rect class="step-bg" x="585" y="418" width="330" height="28" rx="6"/><text class="step" x="750" y="437" text-anchor="middle">6. Select budget account and approve</text>
   <path class="flow lm-flow" d="M950 500 H180"/><rect class="step-bg" x="385" y="478" width="360" height="28" rx="6"/><text class="step" x="565" y="497" text-anchor="middle">7. Redirect to callback with authorization code</text>
   <path class="flow app-flow" d="M170 580 H940"/><rect class="step-bg" x="335" y="558" width="460" height="28" rx="6"/><text class="step" x="565" y="577" text-anchor="middle">8. Exchange code with PKCE (+ client secret for confidential client)</text>