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

package/docs/oauth/register-client.md

@@ -1,51 +0,0 @@
-# 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.
-
-[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
-
-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.
-
-Scopes cannot be changed after registration. While you are developing your application, creating a replacement client is inexpensive, so let the scope set evolve as you learn what the application needs. Aim to have the application's core functionality—and its required permissions—settled before you submit the client for review.
-
-If functionality added after launch needs a scope that is not already registered, you must register a replacement client with the new complete scope set and have it reviewed before rollout. Existing authorizations do not transfer to the replacement client, so users must authorize it before they can use the new functionality. Treat that reauthorization as part of the feature launch: explain what the application can now do with their Lunch Money data and invite them to authorize the replacement client when they want to enable it.
-
-## Choose the client type
-
-Select the type based on whether your application code can keep a client secret secure:
-
-- **Confidential web client:** Choose this when a trusted server can store a client secret, including for applications that are not traditional websites but use a centralized server.
-- **Native or public client:** Choose this for standalone applications installed on a user-controlled device. These clients use PKCE without a client secret. Review the [native application guidance](/oauth/native-apps) before choosing redirects for this type.
-
-The client type cannot be changed after registration. See [OAuth concepts](/oauth/concepts#client-types-and-credentials) for more detail about the two types.
-
-## Register redirect URIs
-
-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.
-
-## 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**.
-
-After registration, record the client ID in your application configuration. A client ID identifies the registration but is not a secret.
-
-If you registered a **Confidential web client**, create a client secret from its details page. Lunch Money shows the secret value only once. Copy it immediately into a secret manager or protected server configuration; it cannot be retrieved later. Never commit it or expose it in browser or mobile code.
-
-A confidential web client can have multiple active secrets. This allows you to introduce a replacement secret, update and verify the deployed application, and then revoke the old secret without interrupting authorization. See [OAuth security guidance](/oauth/security#operate-credentials-safely) when planning ongoing rotation.
-
-You now have the client settings needed to connect your application to Lunch Money.
-
-Next: [Implement authorization](/oauth/authorization-code).

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

@@ -1,57 +0,0 @@
-# OAuth client review and approval
-
-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.
-
-## Lifecycle states
-
-| State | What it means | Owner action |
-| --- | --- | --- |
-| `development` | The client has not been submitted for review; only its owner can authorize it | Configure and test, then request review. |
-| `pending_review` | Review has been requested and is waiting for or receiving review; review-critical fields are frozen | Continue owner testing or cancel the request. |
-| `active` | The review was approved; other Lunch Money users may authorize the application | Operate within the approved identity and scope set. |
-| `rejected` | Changes were requested | Read feedback, revise editable configuration, and resubmit. |
-| `disabled` | Lunch Money disabled the client; its owner is notified, authorization is unavailable, and existing grants no longer work | Review the reason provided and contact developer support when appropriate. |
-
-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.
-
-Before requesting review, provide:
-
-- 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;
-- 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.
-
-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.
-
-## Submit, cancel, or revise
-
-Submitting the request moves the client to `pending_review` and temporarily freezes review-critical fields. Reviews are usually completed within a couple of business days. You can continue developing and testing the application as the client owner while you wait. If you need to change a frozen field, cancel the request to return the client to `development`, make the change, and submit it again.
-
-Lunch Money emails you when the review is complete. You can also check the current status and review history on the client's page in the Developer Portal.
-
-## If review is denied
-
-If the review is denied, the Developer Portal shows feedback explaining what needs to change. Update the client's editable configuration and submit a new review request. Editing the client alone does not resubmit it or clear the `rejected` status.
-
-There is no review comment thread, so use the new request's additional context to explain how you addressed the feedback. The Portal keeps the earlier request in the client's review history.
-
-## After approval
-
-An `active` client can be authorized by other users. Reviewed identity fields, redirect configuration, and the registered scope set remain frozen after approval. Client-secret rotation and revocation remain available subject to lifecycle and security checks.
-
-For an exceptional identity or configuration change, contact [developer support](mailto:developer-support@lunchmoney.app). A scope change always requires a replacement client and user reauthorization.
-
-Next: [Review the security checklist](/oauth/security).

package/docs/oauth/scopes.md

@@ -1,104 +0,0 @@
-# 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.
-
-> [!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.
-
-## Scope groups
-
-Groups are selection shortcuts, not extra permissions. 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
-
-[`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
-
-[`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
-
-[`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
-
-[`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 and attachment metadata | `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-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

@@ -1,44 +0,0 @@
-# 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 budgeting account.
-
-## 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.
-
-## Operate credentials safely
-
-Rotate client secrets on a schedule appropriate for your application's risk and immediately when one may have been exposed. Use overlapping active secrets during a controlled rotation: create the replacement, deploy and verify it, and then revoke the old secret. Coordinate refreshes so two workers do not replay the same rotating token. Make logout revoke server-side credentials and clear local state.
-
-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

@@ -1,66 +0,0 @@
-# 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
-
-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.
-
-Send a form-encoded `grant_type=refresh_token` request to the discovered token endpoint. Confidential clients authenticate with `client_secret_basic`; public clients send their client ID without a secret. A refresh never expands or switches the grant's registered scopes.
-
-Persist every replacement refresh token before discarding the previous value, and serialize refreshes for a grant. Lunch Money rotates refresh tokens; replay of a consumed token can invalidate the token family. If refresh fails terminally, delete unusable credentials and start a fresh authorization.
-
-## Revoke access
-
-Send the token to the discovered revocation endpoint using the authentication method appropriate to the client. Revocation returns success without revealing unnecessary token state. Locally discard the access token, refresh token, and related session state even if the network response is ambiguous.
-
-> [!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.
-
-For a quick development test, the following requests revoke an access token. They assume the values 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_ACCESS_TOKEN" \
-  --data 'token_type_hint=access_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_ACCESS_TOKEN" \
-  --data 'token_type_hint=access_token'
-```
-
-:::
-
-Do not paste a real client secret or token directly into a command where it may be saved in shell history. If the authorization also has a refresh token, revoke or otherwise invalidate it before testing a flow that should require the user to authorize again, then 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.
-
-## 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.

package/docs/oauth/troubleshooting.md

@@ -1,132 +0,0 @@
-# Troubleshoot OAuth
-
-OAuth problems are usually easiest to resolve once you identify where the flow stopped. An OAuth-related failure can occur in one of three places:
-
-- **Authorization and callback:** your application sends the user to Lunch Money to authorize access, then Lunch Money returns the browser to your registered callback.
-- **Token endpoint:** your application exchanges an authorization code for tokens or uses a refresh token to request replacements.
-- **v2 API:** your application presents an access token while making a request for Lunch Money data.
-
-When collecting diagnostic details, preserve nonsensitive information such as timestamps and error names, but leave credentials and full callback URLs out of logs and support messages.
-
-> [!NOTE] Two error formats
-> OAuth protocol endpoints under `/oauth/` use lower-case OAuth error names such as `invalid_grant`. The v2 API uses the Lunch Money response format, with a `message` and an `errors` array whose entries contain `errMsg`.
-
-## Authorization endpoint failures
-
-Authorization can fail before your application reaches the token endpoint. Lunch Money may return a lower-case OAuth error such as `invalid_request`, `invalid_scope`, or `access_denied`.
-
-When Lunch Money can safely use the registered callback, it redirects the user's browser with an `error`, an optional `error_description`, and the original `state` as query parameters:
-
-```text
-https://example.com/oauth/callback?error=access_denied&state=RETURNED_STATE
-```
-
-Match on `error` when it is returned, verify `state`, and treat `error_description` as human-readable text that may change.
-
-| OAuth error | Likely cause | What to do |
-| --- | --- | --- |
-| `invalid_request` | A required parameter is missing, duplicated, or malformed | Compare the request with discovery metadata; send `response_type=code`, exact redirect URI, `state`, and PKCE `S256` values. |
-| `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
-
-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.
-
-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.
-
-## Callback validation failures
-
-After Lunch Money returns the browser to the registered callback, your application must verify that the returned `state` matches the authorization attempt. A missing, changed, or reused value is a state mismatch detected by your application, not an error reported by Lunch Money. Stop the flow, discard the authorization code, clear the one-time state, and begin again. Never exchange the code.
-
-Your application should show the user a safe error message and enough internal reference information for your team to find the failed attempt without exposing the callback URL or its parameters.
-
-## Token endpoint failures
-
-The token endpoint (`POST /oauth/token`) returns OAuth 2.0 errors rather than the Lunch Money v2 API error format. The error name appears in an `error` field and is always lower case:
-
-```json
-{
-  "error": "invalid_grant",
-  "error_description": "grant request is invalid"
-}
-```
-
-Match on `error`. Treat `error_description` as human-readable text that may change; it does not identify the specific cause.
-
-| `error` value | Likely cause | What to do |
-| --- | --- | --- |
-| `invalid_client` | Client authentication is missing or wrong, or Lunch Money disabled the client | Confirm that a confidential client uses HTTP Basic with an active secret and that a public native client sends its client ID without a secret. If previously working credentials are still configured correctly, stop requests and contact [developer support](mailto:developer-support@lunchmoney.app). Reauthorizing users will not restore a disabled client. |
-| `invalid_grant` during code exchange | The code expired, was already used, has the wrong PKCE verifier, or does not match the redirect/client | Start a new authorization. Do not retry the same code. |
-| `invalid_grant` during refresh | The refresh token expired, was revoked, was replayed, or the grant is no longer usable | Stop retrying, discard the token set, and ask the user to authorize again. If the error recurs for the same user shortly after a successful refresh, investigate concurrent refreshes before reauthorizing. |
-
-An `invalid_grant` response does not distinguish a replayed refresh token from one that expired or is otherwise unknown. Recurrence shortly after a successful refresh is the useful signal: Lunch Money rotates refresh tokens on every use, and replaying a consumed token revokes the entire grant. Serialize refreshes for each grant and persist every replacement before discarding the previous token, as described in [Refresh access](/oauth/tokens#refresh-access).
-
-If a successful authorization-code exchange does not include a refresh token, confirm that the client was registered with `offline_access`. If it was not, create a replacement client that includes `offline_access`; test and review it, then reauthorize users. If it was, contact [developer support](mailto:developer-support@lunchmoney.app).
-
-## API failures
-
-Treat an OAuth `401` as an unknown access-token failure unless a refresh request establishes what happened. When an eligible refresh token is available, attempt one refresh and handle the token endpoint's result, which uses the OAuth format shown above rather than the v2 API format:
-
-1. On success, save the replacement tokens and retry the API request once. The access token had merely expired.
-2. On `invalid_grant`, treat the authorization as revoked: mark that user's Lunch Money connection as inactive and discard its tokens. Prompt the user to authorize again the next time they sign in rather than repeatedly interrupting them.
-3. On `invalid_client`, stop requests for every user of the client and contact [developer support](mailto:developer-support@lunchmoney.app). Lunch Money may have disabled the client; retrying or asking users to authorize again will not help.
-
-If no eligible refresh token is available, discard the rejected access token and ask the user to authorize again.
-
-An OAuth access token can fail because it expired, access was revoked, the client was disabled, the user reauthorized the application, a token was revoked or rotated, or the user lost access to the budgeting account. Every OAuth access-token failure returns the same generic `401` response:
-
-```http
-HTTP/1.1 401
-WWW-Authenticate: Bearer error="invalid_token"
-```
-
-```json
-{
-  "message": "Unauthorized",
-  "errors": [
-    {
-      "errMsg": "Access token does not exist."
-    }
-  ]
-}
-```
-
-The response does not identify the cause. Follow the refresh-first recovery path above rather than inferring whether the token expired or another event ended access.
-
-### Insufficient scope
-
-An `insufficient_scope` response cannot be fixed by retrying, refreshing, or asking the user to authorize the existing client again. It means the client was created without all the scopes required for the operation. This applies to development clients as well as approved clients. The only recovery is to [replace the client](#replace-a-client-to-change-scopes).
-
-```http
-HTTP/1.1 403
-WWW-Authenticate: Bearer error="insufficient_scope", scope="transactions:read"
-```
-
-```json
-{
-  "message": "Forbidden",
-  "errors": [
-    {
-      "errMsg": "Required OAuth 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.
-
-### Replace a client to change scopes
-
-Adding `scope` to an authorization URL cannot upgrade or narrow a grant. Lunch Money ignores the requested value and uses the client's complete registered scope set. To change scopes, create a replacement client, test all functionality, complete any required review, update the deployed client ID and credentials, and send every existing user through authorization again.
-
-## Local callback failures
-
-For local development, use a supported loopback host: `localhost`, `127.0.0.1`, or `[::1]`. Matching depends on the client type:
-
-- **Native or public client:** The scheme, host, path, and query string must match exactly. The port is ignored for a loopback redirect, so register one URI without a port, such as `http://localhost/callback`, and let the application use the ephemeral port it binds at runtime.
-- **Confidential web client:** Every component, including the port, must match the registered redirect URI exactly.
-
-Host matching is exact for both client types: a redirect registered with `127.0.0.1` does not match one sent with `localhost`. The browser must also be able to reach the application on the selected host and port. See [development and loopback guidance](/oauth/development#local-loopback-callbacks).
-
-If the safe guidance here does not resolve the problem, contact [developer support](mailto:developer-support@lunchmoney.app) with the client ID, stage, timestamp, and nonsensitive error code. Do not send tokens, secrets, codes, or cookies.

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

@@ -1,32 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="1120" height="780" viewBox="0 0 1120 780" 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 budgeting-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 and calls the API.</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>
-    <marker id="lm-arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#0f766e"/></marker>
-  </defs>
-  <style>
-    .actor{stroke-width:2}.app{fill:#ffedd5;stroke:#b45309}.user{fill:#fef3c7;stroke:#9a6700}.lm{fill:#ccfbf1;stroke:#0f766e}
-    .actor-label{font:700 19px system-ui,sans-serif;fill:#172b2a}.actor-detail{font:14px system-ui,sans-serif;fill:#334e4b}
-    .lifeline{stroke:#94a3b8;stroke-width:2;stroke-dasharray:7 7}.flow{stroke-width:2.5;fill:none}.app-flow{stroke:#b45309;marker-end:url(#app-arrow)}.user-flow{stroke:#9a6700;marker-end:url(#user-arrow)}.lm-flow{stroke:#0f766e;marker-end:url(#lm-arrow)}
-    .step-bg{fill:#fff;stroke:#cbd5e1;stroke-width:1}.step{font:600 14px system-ui,sans-serif;fill:#172b2a}
-  </style>
-  <rect class="actor app" x="40" y="25" width="260" height="72" rx="12"/>
-  <text class="actor-label" x="170" y="56" text-anchor="middle">Your application</text><text class="actor-detail" x="170" y="79" text-anchor="middle">browser route and server</text>
-  <rect class="actor user" x="430" y="25" width="260" height="72" rx="12"/>
-  <text class="actor-label" x="560" y="56" text-anchor="middle">Lunch Money user</text><text class="actor-detail" x="560" y="79" text-anchor="middle">browser, sign-in, and approval</text>
-  <rect class="actor lm" x="820" y="25" width="260" height="72" rx="12"/>
-  <text class="actor-label" x="950" y="56" text-anchor="middle">Lunch Money</text><text class="actor-detail" x="950" y="79" text-anchor="middle">authorization server and API</text>
-  <path class="lifeline" d="M170 105 V750"/><path class="lifeline" d="M560 105 V750"/><path class="lifeline" d="M950 105 V750"/>
-  <path class="flow app-flow" d="M170 140 H550"/><rect class="step-bg" x="278" y="118" width="180" height="28" rx="6"/><text class="step" x="368" y="137" text-anchor="middle">1. Redirect the user</text>
-  <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="590" y="358" width="340" height="28" rx="6"/><text class="step" x="760" y="377" text-anchor="middle">5. Present account and permission choices</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 budgeting 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>
-  <path class="flow lm-flow" d="M950 640 H180"/><rect class="step-bg" x="385" y="618" width="360" height="28" rx="6"/><text class="step" x="565" y="637" text-anchor="middle">9. Return access token + optional refresh token</text>
-  <path class="flow app-flow" d="M170 710 H940"/><rect class="step-bg" x="466" y="688" width="198" height="28" rx="6"/><text class="step" x="565" y="707" text-anchor="middle">10. Call the V2 API</text>
-</svg>

package/v2/images/oauth-token-lifecycle.svg

@@ -1,14 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="990" height="300" viewBox="0 0 990 300" role="img" aria-labelledby="title desc">
-  <title id="title">OAuth token lifecycle and recovery</title>
-  <desc id="desc">Authorization yields a short-lived access token and, when offline access applies, a finite refresh token. Refresh replaces tokens. Expiration, revocation, or a terminal refresh failure leads to fresh authorization.</desc>
-  <defs><marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#0f766e"/></marker></defs>
-  <style>.box{fill:#f0f9f8;stroke:#2a6b64;stroke-width:2}.warn{fill:#fff4dc;stroke:#9a6a16;stroke-width:2}.label{font:600 17px system-ui,sans-serif;fill:#173f3b}.small{font:14px system-ui,sans-serif;fill:#294744}.line{stroke:#0f766e;stroke-width:2.5;fill:none;marker-end:url(#arrow)}.annotation-bg{fill:#fff;stroke:#cbd5e1;stroke-width:1}.annotation{font:600 14px system-ui,sans-serif;fill:#172b2a}</style>
-  <rect class="box" x="35" y="65" width="180" height="70" rx="12"/><text class="label" x="125" y="94" text-anchor="middle">Authorization</text><text class="small" x="125" y="117" text-anchor="middle">user present</text>
-  <rect class="box" x="300" y="35" width="200" height="70" rx="12"/><text class="label" x="400" y="64" text-anchor="middle">Access token</text><text class="small" x="400" y="87" text-anchor="middle">short-lived</text>
-  <rect class="box" x="300" y="165" width="200" height="70" rx="12"/><text class="label" x="400" y="194" text-anchor="middle">Refresh token</text><text class="small" x="400" y="217" text-anchor="middle">finite; offline_access</text>
-  <rect class="box" x="590" y="100" width="170" height="70" rx="12"/><text class="label" x="675" y="129" text-anchor="middle">Refresh</text><text class="small" x="675" y="152" text-anchor="middle">store replacements</text>
-  <rect class="warn" x="790" y="100" width="140" height="70" rx="12"/><text class="label" x="860" y="129" text-anchor="middle">Terminal failure</text><text class="small" x="860" y="152" text-anchor="middle">reauthorize</text>
-  <path class="line" d="M215 88 L290 72"/><path class="line" d="M215 112 L290 185"/><path class="line" d="M500 200 L580 150"/><path class="line" d="M760 135 H780"/><path class="line" d="M675 95 C675 25 500 15 470 35"/>
-  <rect class="annotation-bg" x="530" y="10" width="170" height="28" rx="6"/><text class="annotation" x="615" y="29" text-anchor="middle">replacement token set</text>
-  <rect class="annotation-bg" x="740" y="198" width="240" height="36" rx="6"/><text class="annotation" x="860" y="221" text-anchor="middle">expired, revoked, or rejected</text>
-</svg>