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

package/docs/oauth/troubleshooting.md

@@ -1,159 +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.
-
-For a runnable comparison, [try OAuth with the confidential Node.js sample](/oauth/sample-applications#try-oauth-with-your-lunch-money-account). Reproduce the same stage in its end-to-end flow, then compare the result with the sample repository's [troubleshooting guide](https://github.com/lunch-money/lm-oauth-confidential-node-example/blob/main/TROUBLESHOOTING.md) without copying credentials or full callback URLs.
-
-> [!NOTE] Two error formats
-> OAuth protocol endpoints under `/oauth/` use lower-case OAuth error names such as `invalid_grant`. The v2 API uses the Lunch Money response format, with a `message` and an `errors` array whose entries contain `errMsg`.
-
-## 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. |
-
-### Users cannot authorize an unapproved client
-
-Until a client is approved, only its owner may authorize the application. Anyone else is stopped at the consent screen and is never returned to your application, so you will see no callback and no `error` parameter for these attempts.
-
-Those users are shown the support email registered with your client so they can reach you. If you did not expect authorization to be unavailable, check the client in the [Developer Portal](/oauth/applications). A client stays in development until it is submitted for review and approved. A rejected or disabled client also prevents other users from authorizing the application.
-
-### Redirect URI problems
-
-If the callback address cannot be matched to one registered for the client, Lunch Money cannot safely return the browser to your application. It stops locally and shows the user a page explaining what happened, rather than redirecting with an `error`. Your application receives no callback for these attempts.
-
-The page displays one of two codes, a UTC timestamp, and the application name and public client ID once the client has been resolved.
-
-| Code | Likely cause | What to do |
-| --- | --- | --- |
-| `redirect_uri_mismatch` | The address your application sent is not registered for the client, or differs from a registered one | Open the client in the [Developer Portal](/oauth/applications) and compare the address with its registered redirect URIs. Web-client redirects and native HTTPS or private-use scheme redirects must match every component exactly. For a native HTTP loopback redirect, the scheme, host, path, and query string must match, but the ephemeral port may differ. See [local callback failures](#local-callback-failures). |
-| `redirect_uri_missing` | No `redirect_uri` was sent, and the client has more than one registered, so Lunch Money cannot choose | Send the parameter explicitly. A client with exactly one registered address may omit it; Lunch Money then uses the registered value. |
-
-The page offers the user a prefilled message addressed to the support email registered with your client. It contains the error code, the timestamp, the application name and client ID, and the callback address your application sent, reduced to its origin and path with any query string removed. Compare that sanitized callback address with the redirect URIs registered for the client, then correct either the registered URI or the address your application sends.
-
-## Callback validation failures
-
-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 that connection as revoked: mark the connection for the selected user/account as inactive and discard its tokens. Prompt the user to authorize that connection again the next time they need it rather than repeatedly interrupting them. Leave the user's other budgeting-account connections unchanged.
-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 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.
-
-## Client-management failures
-
-The Developer Portal can return structured errors when you register clients, create client secrets, or submit a client for review. These errors use the Lunch Money response format, not OAuth protocol errors such as `invalid_grant`.
-
-| Status and code | Meaning | What to do |
-| --- | --- | --- |
-| `422 quota_exceeded`, field `clients` | You already own 25 non-deleted OAuth clients. | Delete a client you no longer use before registering another. |
-| `422 quota_exceeded`, field `secrets` | The client already has three non-revoked secrets. Expired secrets still count. | Revoke an obsolete or expired secret before creating another. |
-| `429 review_quota_exceeded` | You have made five initial review submissions across your clients in the rolling 24-hour window. | Wait until the time shown in the Developer Portal before submitting again. API clients should also respect the `Retry-After` response header. |
-
-Cancelled submissions, rejected-client resubmissions, and submissions for clients later deleted still count toward the review limit. Reviews opened automatically after an active client's identity changes do not count.
-
-## 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,35 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="1120" height="960" viewBox="0 0 1120 960" role="img" aria-labelledby="title desc">
-  <title id="title">Lunch Money OAuth authorization-code flow</title>
-  <desc id="desc">A sequence diagram with three actors: your application, the Lunch Money user, and Lunch Money. The application redirects the user's browser to Lunch Money. When necessary, Lunch Money presents its sign-in screen and the user signs in directly with Lunch Money. Lunch Money then presents the 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. The application calls GET /v2/me, saves the identified connection, and calls the API for that account.</desc>
-  <defs>
-    <marker id="app-arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#b45309"/></marker>
-    <marker id="user-arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto"><path d="M0,0 L0,6 L9,3 z" fill="#9a6700"/></marker>
-    <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 V930"/><path class="lifeline" d="M560 105 V930"/><path class="lifeline" d="M950 105 V930"/>
-  <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="545" y="358" width="430" height="28" rx="6"/><text class="step" x="760" y="377" text-anchor="middle">5. Present budgeting-account selector and permissions</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 700 H940"/><rect class="step-bg" x="430" y="678" width="270" height="28" rx="6"/><text class="step" x="565" y="697" text-anchor="middle">10. Call GET /v2/me</text>
-  <path class="flow lm-flow" d="M950 760 H180"/><rect class="step-bg" x="350" y="738" width="430" height="28" rx="6"/><text class="step" x="565" y="757" text-anchor="middle">11. Return user id, account_id, and budget_name</text>
-  <path class="flow app-flow" d="M170 800 H330 V840 H180"/><rect class="step-bg" x="285" y="798" width="330" height="28" rx="6"/><text class="step" x="450" y="817" text-anchor="middle">12. Save connection and make it active</text>
-  <path class="flow app-flow" d="M170 890 H940"/><rect class="step-bg" x="385" y="868" width="360" height="28" rx="6"/><text class="step" x="565" y="887" text-anchor="middle">13. Call the V2 API for the active account</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>