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

package/docs/oauth/sample-applications.md

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

package/docs/oauth/scopes.md

@@ -0,0 +1,104 @@
+# OAuth scopes
+
+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 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 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
+
+View all supported Lunch Money data without changing it
+
+[`me:read`](#scope-me-read), [`summary:read`](#scope-summary-read), [`categories:read`](#scope-categories-read), [`crypto_manual:read`](#scope-crypto-manual-read), [`crypto_synced:read`](#scope-crypto-synced-read), [`balance_history:read`](#scope-balance-history-read), [`manual_accounts:read`](#scope-manual-accounts-read), [`plaid_accounts:read`](#scope-plaid-accounts-read), [`transactions:read`](#scope-transactions-read), [`transaction_attachments:read`](#scope-transaction-attachments-read), [`tags:read`](#scope-tags-read), [`recurring_items:read`](#scope-recurring-items-read), [`budgets:read`](#scope-budgets-read)
+
+### Transactions
+
+Import, export, organize, and manage transactions and their attachments
+
+[`me:read`](#scope-me-read), [`transactions:read`](#scope-transactions-read), [`transactions:create`](#scope-transactions-create), [`transactions:update`](#scope-transactions-update), [`transactions:delete`](#scope-transactions-delete), [`transaction_attachments:read`](#scope-transaction-attachments-read), [`transaction_attachments:create`](#scope-transaction-attachments-create), [`transaction_attachments:delete`](#scope-transaction-attachments-delete), [`categories:read`](#scope-categories-read), [`tags:read`](#scope-tags-read), [`manual_accounts:read`](#scope-manual-accounts-read), [`plaid_accounts:read`](#scope-plaid-accounts-read), [`recurring_items:read`](#scope-recurring-items-read)
+
+### Budgeting
+
+Analyze and manage budgets, categories, and tags
+
+[`me:read`](#scope-me-read), [`summary:read`](#scope-summary-read), [`budgets:read`](#scope-budgets-read), [`budgets:update`](#scope-budgets-update), [`budgets:delete`](#scope-budgets-delete), [`categories:read`](#scope-categories-read), [`categories:create`](#scope-categories-create), [`categories:update`](#scope-categories-update), [`categories:delete`](#scope-categories-delete), [`tags:read`](#scope-tags-read), [`tags:create`](#scope-tags-create), [`tags:update`](#scope-tags-update), [`tags:delete`](#scope-tags-delete), [`recurring_items:read`](#scope-recurring-items-read)
+
+### Accounts
+
+Manage accounts, balances, and balance history
+
+[`me:read`](#scope-me-read), [`manual_accounts:read`](#scope-manual-accounts-read), [`manual_accounts:create`](#scope-manual-accounts-create), [`manual_accounts:update`](#scope-manual-accounts-update), [`manual_accounts:delete`](#scope-manual-accounts-delete), [`plaid_accounts:read`](#scope-plaid-accounts-read), [`plaid_accounts:update`](#scope-plaid-accounts-update), [`crypto_manual:read`](#scope-crypto-manual-read), [`crypto_manual:create`](#scope-crypto-manual-create), [`crypto_manual:update`](#scope-crypto-manual-update), [`crypto_manual:delete`](#scope-crypto-manual-delete), [`crypto_synced:read`](#scope-crypto-synced-read), [`crypto_synced:update`](#scope-crypto-synced-update), [`balance_history:read`](#scope-balance-history-read), [`balance_history:update`](#scope-balance-history-update), [`balance_history:delete`](#scope-balance-history-delete)
+
+### Organize
+
+Manage categories and tags used to organize transactions
+
+[`me:read`](#scope-me-read), [`categories:read`](#scope-categories-read), [`categories:create`](#scope-categories-create), [`categories:update`](#scope-categories-update), [`categories:delete`](#scope-categories-delete), [`tags:read`](#scope-tags-read), [`tags:create`](#scope-tags-create), [`tags:update`](#scope-tags-update), [`tags:delete`](#scope-tags-delete), [`recurring_items:read`](#scope-recurring-items-read)
+
+### Full access
+
+View and manage all supported Lunch Money data
+
+[`me:read`](#scope-me-read), [`me:update`](#scope-me-update), [`summary:read`](#scope-summary-read), [`categories:read`](#scope-categories-read), [`categories:create`](#scope-categories-create), [`categories:update`](#scope-categories-update), [`categories:delete`](#scope-categories-delete), [`crypto_manual:read`](#scope-crypto-manual-read), [`crypto_manual:create`](#scope-crypto-manual-create), [`crypto_manual:update`](#scope-crypto-manual-update), [`crypto_manual:delete`](#scope-crypto-manual-delete), [`crypto_synced:read`](#scope-crypto-synced-read), [`crypto_synced:update`](#scope-crypto-synced-update), [`balance_history:read`](#scope-balance-history-read), [`balance_history:update`](#scope-balance-history-update), [`balance_history:delete`](#scope-balance-history-delete), [`manual_accounts:read`](#scope-manual-accounts-read), [`manual_accounts:create`](#scope-manual-accounts-create), [`manual_accounts:update`](#scope-manual-accounts-update), [`manual_accounts:delete`](#scope-manual-accounts-delete), [`plaid_accounts:read`](#scope-plaid-accounts-read), [`plaid_accounts:update`](#scope-plaid-accounts-update), [`transactions:read`](#scope-transactions-read), [`transactions:create`](#scope-transactions-create), [`transactions:update`](#scope-transactions-update), [`transactions:delete`](#scope-transactions-delete), [`transaction_attachments:read`](#scope-transaction-attachments-read), [`transaction_attachments:create`](#scope-transaction-attachments-create), [`transaction_attachments:delete`](#scope-transaction-attachments-delete), [`tags:read`](#scope-tags-read), [`tags:create`](#scope-tags-create), [`tags:update`](#scope-tags-update), [`tags:delete`](#scope-tags-delete), [`recurring_items:read`](#scope-recurring-items-read), [`budgets:read`](#scope-budgets-read), [`budgets:update`](#scope-budgets-update), [`budgets:delete`](#scope-budgets-delete)
+
+## Resource scopes
+
+| Scope | What it allows | V2 operations |
+| --- | --- | --- |
+| <a id="scope-me-read"></a>`me:read` | View your Lunch Money identity and account, user, and budget settings | `getMe`, `getAccountSettings`, `getUserSettings`, `getUserAccountSettings` |
+| <a id="scope-me-update"></a>`me:update` | Update your Lunch Money account, user, and budget settings | `updateAccountSettings`, `updateUserSettings`, `updateUserAccountSettings` |
+| <a id="scope-summary-read"></a>`summary:read` | View your budget summary | `getBudgetSummary` |
+| <a id="scope-categories-read"></a>`categories:read` | View categories and category groups | `getAllCategories`, `getCategoryById` |
+| <a id="scope-categories-create"></a>`categories:create` | Create categories and category groups | `createCategory` |
+| <a id="scope-categories-update"></a>`categories:update` | Update categories and category groups | `updateCategory` |
+| <a id="scope-categories-delete"></a>`categories:delete` | Delete categories and category groups | `deleteCategory` |
+| <a id="scope-crypto-manual-read"></a>`crypto_manual:read` | View supported cryptocurrencies and manually managed cryptocurrency balances | `getAllCryptocurrencies`, `getAllCryptoManual`, `getCryptoManualById` |
+| <a id="scope-crypto-manual-create"></a>`crypto_manual:create` | Add supported cryptocurrencies and create manually managed cryptocurrency balances | `createCryptocurrency`, `createCryptoManual` |
+| <a id="scope-crypto-manual-update"></a>`crypto_manual:update` | Update manually managed cryptocurrency balances | `updateCryptoManual` |
+| <a id="scope-crypto-manual-delete"></a>`crypto_manual:delete` | Delete manually managed cryptocurrency balances | `deleteCryptoManual` |
+| <a id="scope-crypto-synced-read"></a>`crypto_synced:read` | View synced cryptocurrency accounts and balances | `getAllCryptoSynced`, `getCryptoSyncedById`, `getCryptoSyncedBalanceBySymbol` |
+| <a id="scope-crypto-synced-update"></a>`crypto_synced:update` | Refresh balances for synced cryptocurrency accounts | `refreshCryptoSynced` |
+| <a id="scope-balance-history-read"></a>`balance_history:read` | View balance history for accounts and synced cryptocurrency balances | `getBalanceHistory`, `getBalanceHistoryForAccount`, `getBalanceHistoryForCryptoSynced` |
+| <a id="scope-balance-history-update"></a>`balance_history:update` | Create or update balance history and details for deleted accounts | `upsertBalanceHistoryForAccount`, `upsertBalanceHistoryForCryptoSynced`, `updateBalanceHistoryDetails` |
+| <a id="scope-balance-history-delete"></a>`balance_history:delete` | Delete balance history for accounts and synced cryptocurrency balances | `deleteBalanceHistoryForAccount`, `deleteBalanceHistoryForCryptoSynced`, `deleteBalanceHistoryEntry` |
+| <a id="scope-manual-accounts-read"></a>`manual_accounts:read` | View manually managed accounts | `getAllManualAccounts`, `getManualAccountById` |
+| <a id="scope-manual-accounts-create"></a>`manual_accounts:create` | Create manually managed accounts | `createManualAccount` |
+| <a id="scope-manual-accounts-update"></a>`manual_accounts:update` | Update manually managed accounts | `updateManualAccount` |
+| <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 | `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` | 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` |
+| <a id="scope-tags-create"></a>`tags:create` | Create tags | `createTag` |
+| <a id="scope-tags-update"></a>`tags:update` | Update tags | `updateTag` |
+| <a id="scope-tags-delete"></a>`tags:delete` | Delete tags | `deleteTag` |
+| <a id="scope-recurring-items-read"></a>`recurring_items:read` | View recurring items | `getAllRecurring`, `getRecurringById` |
+| <a id="scope-budgets-read"></a>`budgets:read` | View budget period settings | `getBudgetSettings` |
+| <a id="scope-budgets-update"></a>`budgets:update` | Create or update budget amounts | `upsertBudget` |
+| <a id="scope-budgets-delete"></a>`budgets:delete` | Delete budget amounts | `deleteBudget` |
+
+## Continued access
+
+<a id="scope-offline-access"></a>
+
+### `offline_access`
+
+Allow this app to maintain access without asking you to sign in and authorize it again
+
+`offline_access` is not permission to a V2 resource. It allows an eligible token response to include a longer-lived, finite refresh token. Your application must still request every resource scope it needs when the client is created.
+
+## Find the scope for an endpoint
+
+The [V2 API reference](/v2/docs) displays the required OAuth scope for each operation. Scope requirements come from the same catalog and standard OpenAPI security metadata used to generate this page.
+
+Next: [Implement the authorization-code flow](/oauth/authorization-code).

package/docs/oauth/security.md

@@ -0,0 +1,78 @@
+# OAuth security guidance
+
+OAuth gives your application permission to work with a user's Lunch Money data. A few deliberate choices about credential storage, callbacks, logging, and recovery help you protect that access and earn users' trust.
+
+Before a client can be approved for use by other Lunch Money users, its application must have a publicly accessible privacy policy. The policy gives users a place to understand how the application handles their data before they authorize it. See [application review and approval](/oauth/review-and-approval) for the complete review requirements.
+
+## Protect credentials
+
+- Keep confidential-client secrets and refresh tokens on the server and in a secret manager or encrypted credential store.
+- Never put a client secret in browser JavaScript, a mobile binary, a URL, source control, analytics, or a support ticket.
+- Avoid logging authorization codes, access tokens, refresh tokens, session cookies, callback query strings, or secrets.
+- Redact credentials from errors and tracing before data leaves the process.
+- Use HTTPS outside the explicitly supported loopback-development case.
+
+## Decide where your web application uses access tokens
+
+A web application can keep access tokens on its server and have browser code call its own backend. Where direct browser access to the API is supported, it can instead make access tokens available to browser code and call the Lunch Money API from there. OAuth does not require one architecture for every application.
+
+Keeping access tokens on the server reduces their exposure to browser code. Using them in the browser can simplify some applications and makes it easier for the signed-in user or support team to inspect Lunch Money API requests and responses in the browser's Network panel.
+
+In the browser-based model, the short-lived access token is also visible to the signed-in user in the request's `Authorization` header. That visibility is expected and is not, by itself, a credential leak. The tradeoff is that a malicious script running on the page—or someone with access to that browser session—could copy the bearer token and use it until it expires or is revoked.
+
+If your browser code uses access tokens, keep them available for no longer than necessary, avoid persistent browser storage when practical, and protect the application against cross-site scripting. Regardless of the architecture, keep the client secret and refresh tokens on the server, never put bearer tokens in URLs or logs, and associate each authorization with the correct application user and Lunch Money budget account.
+
+## Associate credentials with your application user
+
+A confidential application must authenticate its own user before starting Lunch Money OAuth. Bind each authorization attempt to that authenticated user's server-side session, then recover the owner from the consumed server-side attempt after the callback is verified. Do not let the callback choose who owns the resulting credentials.
+
+Store each budget-account connection under a stable internal application-user ID. Within that owner, use both the Lunch Money user `id` and budget-account `account_id` returned by `GET /v2/me` as the provider identity. Your database may assign a separate internal connection ID for routing and references; it does not replace the `(application user ID, Lunch Money user id, account_id)` fields used to create or update a provider connection. Do not use an email address, callback parameter, form field, browser cookie, or other browser-supplied value to establish the credential owner or provider identity.
+
+An application user may own connections for more than one Lunch Money user, although applications do not have to expose that capability. If your application supports only one Lunch Money identity per application user, detect a different `id` after `GET /v2/me` and handle it explicitly; never overwrite the existing identity's credentials.
+
+```text
+Authenticated application user
+  -> owned connection (Lunch Money user id + account_id)
+     -> encrypted credential set
+```
+
+When the user returns to your application, authenticate them through your application's own sign-in system before listing or using their saved connections. Knowing a Lunch Money `id`, `account_id`, or internal connection ID does not prove ownership. Limit connection lookups to the authenticated application user's records, and reject requests for a connection they do not own before loading its credentials.
+
+For example, if Alex and Sam both use your application, Sam must not be able to use Alex's saved credentials by submitting Alex's connection ID. This remains true even if they both have access to the same Lunch Money budget account. Each application user must authorize their own connection. If Alex has authorized two budget accounts, both connections belong to Alex's application user and may be listed and selected within Alex's authenticated session. Each connection still uses the credential set for its own Lunch Money `id`/`account_id` pair.
+
+Enforce this ownership and identity check for every API request, refresh, reauthorization, revocation, and deletion involving a saved connection. Background jobs must carry the connection's stored owner and identity so they use the same checks without an interactive session. Updating credentials after reauthorization must remain within the original application user's connections and match both the returned Lunch Money `id` and `account_id`. A different Lunch Money user authorizing the same shared account must not silently overwrite an existing connection.
+
+Durable credentials must be encrypted at rest, and backend access should be limited to the services and operators that need it. Encryption protects stored secrets; your application must still enforce ownership when it reads or uses them. Never return refresh tokens or client secrets to browser JavaScript. List connections using non-secret metadata such as `budget_name`, and keep their credentials in the protected store.
+
+Apply API calls, refresh, revocation, local deletion, and caches only to the active Lunch Money user and budget-account connection. Disconnecting a budget account should revoke continuing access for that connection and remove its locally stored credentials while keeping the active user's other connections intact. If the active user's final connection is removed, enter a disconnected state rather than falling back to another Lunch Money user's hidden connection.
+
+On application sign-out or Lunch Money user switching, clear session-specific selections and displayed or cached data so the newly active identity cannot see the previous identity's information. An application may retain the previous Lunch Money user's encrypted credentials when its ownership model permits it, but those connections must remain hidden and unavailable until that identity becomes active again. It may instead delete credentials during its own sign-out or switching lifecycle; that is an application policy.
+
+Keep remote revocation and local credential deletion separate. A local-only “forget” action does not end the remote authorization, so confirm that action and explain that access remains active at Lunch Money. Signing out of your application, hiding a retained connection, forgetting a local credential, and disconnecting Lunch Money are distinct lifecycle events.
+
+The [confidential Node.js sample](/oauth/sample-applications#understand-the-confidential-teaching-code) makes this boundary explicit in its [`CredentialStore`](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/main/src/oauth/tokens.ts) abstraction. Its [security guide](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/main/SECURITY.md) explains the threat model, and its [production checklist](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/main/PRODUCTION_CHECKLIST.md) lists the storage, tenant-isolation, lifecycle, and operational work the teaching sample deliberately omits. Those boundaries matter, but their implementation and database schema are specific to your application.
+
+## Secure authorization and callbacks
+
+- Generate unpredictable, session-bound, single-use `state` and verify it before exchanging a code.
+- Use PKCE with `S256` for every authorization.
+- Require an exact registered redirect URI and prevent open redirects behind the callback.
+- Exchange each authorization code once and remove callback parameters from the visible URL.
+- Keep authorization results out of browser history where practical and return `Cache-Control: no-store` for sensitive responses.
+- Launch native authorization in the platform browser, never an embedded WebView.
+
+## Minimize authority
+
+Choose only the resource scopes needed for expected features. Add `offline_access` only for genuine unattended operation. Remember that scope changes require a replacement client and reauthorization; they cannot be requested dynamically.
+
+## Keep the support address confirmed
+
+Use a monitored support mailbox that your team controls, and keep it current in the Developer Portal. Lunch Money sends client notifications to a support address only after someone with access to that mailbox confirms it. Changing the address clears its confirmation, so follow the new confirmation link before relying on that mailbox for notifications.
+
+## Operate credentials safely
+
+Rotate client secrets on a schedule appropriate for your application's risk and immediately when one may have been exposed. A client can have up to three non-revoked secrets, so confirm that it has room before starting a rotation. Expired secrets still count toward this limit until you revoke them. Use overlapping active secrets during a controlled rotation: create the replacement, deploy and verify it, and then revoke the old secret. Coordinate refreshes so two workers do not replay the same rotating token, and atomically persist every complete replacement credential set. Production storage needs database transactions, distributed per-connection locking, recovery when persistence fails, multi-instance coordination, and tenant isolation. Make disconnect invalidate continuing refresh access as well as clear local state.
+
+If a credential may have been exposed, stop using it, revoke it, rotate the relevant client secret, review logs without copying secret values, and require reauthorization when the grant can no longer be trusted.
+
+Next: [Review token recovery](/oauth/tokens) and [troubleshoot failures](/oauth/troubleshooting).

package/docs/oauth/tokens.md

@@ -0,0 +1,83 @@
+# Token lifecycle and recovery
+
+Treat expiration, refresh, revocation, and reauthorization as separate events. Your integration should expect every token to stop working eventually.
+
+![Token lifecycle: authorization produces an access token and sometimes a refresh token; access tokens expire, refresh may replace tokens, and terminal failures lead to reauthorization.](/v2/images/oauth-token-lifecycle.svg)
+
+Teal boxes show the normal token lifecycle. The amber box marks a terminal failure that requires the user to authorize again.
+
+## Determine expiration
+
+Keep each token set associated with the application user and the authorized Lunch Money user and budget account pair. Renewing credentials does not change that pair; selecting another budget account requires a new authorization. See [users, budget accounts, and access tokens](/oauth/concepts#users-budget-accounts-and-access-tokens).
+
+Access tokens are deliberately short-lived. Record when the token response arrives and add its `expires_in` duration to determine the expected expiry. Refresh slightly before that point while accounting for clock skew. Do not parse the opaque access token or assume a fixed lifetime.
+
+## Refresh access
+
+A refresh token is issued after a successful authorization-code exchange only when the registered client includes `offline_access`. It lasts longer than an access token, but it is not permanent.
+
+The [confidential Node.js sample](/oauth/sample-applications#try-oauth-with-your-lunch-money-account) keeps refresh optional within its first-run walkthrough. Register the sample client with `offline_access` to exercise the refresh branch, or omit it to focus on authorization, `GET /v2/me`, revocation, and reauthorization.
+
+Send a form-encoded `grant_type=refresh_token` request to the discovered token endpoint. Confidential clients authenticate with `client_secret_basic`; public clients send their client ID without a secret. A refresh never expands or switches the grant's registered scopes, Lunch Money user, or budget-account identity.
+
+Atomically persist the complete replacement token set before discarding the previous value, and serialize refreshes for each active application-user and Lunch Money user/account connection. When more than one process can refresh the same connection, use a shared credential store and a cross-process lock. After acquiring the lock, re-read the stored refresh token because another process may already have replaced it. Persist the complete replacement set before using the new access token or releasing the lock.
+
+Lunch Money rotates refresh tokens on every successful refresh. A consumed token cannot be retried: replay revokes the token family. If the response to a successful refresh is lost before the replacement set is saved, require the user to authorize again rather than retrying the previous token. Treat other transient failures according to a bounded retry policy, but treat `invalid_grant` as terminal: delete unusable credentials for that connection and start a fresh authorization.
+
+## Revoke access
+
+To invalidate a complete authorization, send the active connection's current refresh token to `POST /oauth/revoke` using the authentication method appropriate to the client. This revokes the grant and every access token and refresh token in its token family. Locally discard that connection's token set and related session state even if the network response is ambiguous. Keep other user/account connections unchanged, including connections to another budget account for the same Lunch Money user.
+
+> [!TIP] Revocation endpoint
+> The currently resolved endpoint is `https://api.lunchmoney.dev/oauth/revoke`. Use authorization-server discovery to configure deployed applications so they receive the current endpoint automatically.
+
+> [!WARNING] Revoke before replacement authorization
+> Reauthorization may reuse the existing grant. Revoke its current refresh token before starting replacement authorization. Revoking the old refresh token after the new exchange also revokes the credentials returned by that exchange.
+
+Revoke the complete authorization only when you must invalidate every copy of its credentials—for example, after suspected credential exposure or when signing every installation or shared-backend session out. For a normal reconnection, keep the grant and atomically replace the connection's locally stored token set with the successful exchange response.
+
+The following requests revoke the complete authorization. They assume the current refresh token and client credentials have already been loaded into shell variables from your secure development configuration.
+
+:::tabs
+
+@tab Confidential web client
+
+```bash
+curl --request POST 'https://api.lunchmoney.dev/oauth/revoke' \
+  --user "$LUNCH_MONEY_CLIENT_ID:$LUNCH_MONEY_CLIENT_SECRET" \
+  --header 'Content-Type: application/x-www-form-urlencoded' \
+  --data-urlencode "token=$LUNCH_MONEY_REFRESH_TOKEN" \
+  --data 'token_type_hint=refresh_token'
+```
+
+@tab Native or public client
+
+```bash
+curl --request POST 'https://api.lunchmoney.dev/oauth/revoke' \
+  --header 'Content-Type: application/x-www-form-urlencoded' \
+  --data-urlencode "client_id=$LUNCH_MONEY_CLIENT_ID" \
+  --data-urlencode "token=$LUNCH_MONEY_REFRESH_TOKEN" \
+  --data 'token_type_hint=refresh_token'
+```
+
+:::
+
+The optional `token_type_hint` may be `access_token` or `refresh_token`. To revoke only the current access token, send that token as `token` with `token_type_hint=access_token`. An active refresh token remains usable and can obtain a replacement access token.
+
+Do not paste a real client secret or token directly into a command where it may be saved in shell history. After revoking the complete authorization, discard both tokens locally.
+
+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.
+
+An application that no longer has the current refresh token cannot revoke the complete authorization. Direct the Lunch Money user to the [Connected Apps page](https://my.lunchmoney.app/connected-apps) to disconnect it. User revocation applies to the selected Lunch Money user and budget-account authorization. Your application should treat the resulting authentication failure as terminal for that connection and ask the user to authorize it again when they want to reconnect. Keep every stored Lunch Money user/account connection independent, including when two users have authorized the same shared `account_id`.
+
+Remote revocation is different from local credential deletion. If an application offers a local-only “forget” action, confirm it and explain that the remote authorization remains active. Removing the active user's final local connection should leave the application disconnected rather than expose a hidden connection belonging to another Lunch Money user.
+
+## Recovery rules
+
+- A rejected API request may mean the access token expired, was revoked, lacks the required scope, targets the wrong resource, or no longer maps to an accessible account. The `401` response does not identify which cause applies. Follow the [API failure decision tree](/oauth/troubleshooting#api-failures).
+- Retry once only after a coordinated successful refresh; do not loop on authentication errors.
+- Treat a rejected refresh token as a signal to reauthorize, not as a reason to retry indefinitely.
+- Preserve no fixed lifetime assumption in jobs, queues, or database schemas.
+- Ask the user to authorize again after terminal grant or refresh failure.
+
+See [troubleshooting](/oauth/troubleshooting) for error-specific guidance.