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

package/README.md

@@ -45,10 +45,22 @@ const intro = fs.readFileSync(path.join(docsRoot, 'docs/getting-started.md'), 'u
     }
   ],
   "redirects": [ /* { from, to, status } */ ],
-  "sidebar": { "docs": [ /* … */ ], "v1": [ /* … */ ] }
+  "sidebar": {
+    "docs": [
+      {
+        "section": "OAUTH",
+        "collapsed": true, // optional; initially collapse this section
+        "items": [ /* { label, path, external? } */ ]
+      }
+    ],
+    "v1": [ /* … */ ]
+  }
 }
 ```
 
+Sidebar sections initially appear expanded unless their optional `collapsed`
+property is `true`.
+
 ## Versioning
 
 The package version tracks the newest API version this content documents (e.g. `2.11.x`

package/docs/STYLE_GUIDE.md

@@ -0,0 +1,84 @@
+# Documentation style guide
+
+Use this guide for hand-written Markdown in `docs/` and `v2/docs/`. Preserve
+intentional conventions in generated pages, the v1 Slate reference, and version
+history entries.
+
+## Voice and structure
+
+- Address the reader as “you” and use direct, practical language.
+- Start with the reader's goal before introducing protocol or API details.
+- Use one H1 per page and keep heading levels in logical order.
+- Use sentence case for prose headings. Preserve official names, initialisms,
+  endpoint paths, property names, and exact UI labels.
+- Add a next step when a guide belongs to a longer reader journey. Use
+  `## Need help?` only when the page provides support options.
+
+## Terminology
+
+- Use “Lunch Money” for the product and “Lunchbag Labs, Inc.” only when the
+  legal company name is required.
+- Use “Developer Portal,” “Developers page,” and “API reference” consistently.
+  Preserve different capitalization only for an exact UI label.
+- Write “v1” and “v2” in prose. Use “V2 API” only where it is an established
+  proper label, such as the rendered reference title.
+- Distinguish authentication from authorization, personal access tokens from
+  OAuth access tokens, and applications from their registered OAuth clients.
+
+## Code and placeholders
+
+- Format endpoints, properties, headers, status codes, commands, filenames,
+  scope names, and literal values as code.
+- Use `YOUR_ACCESS_TOKEN` as the generic access-token placeholder. Environment
+  variable examples may use `LUNCH_MONEY_ACCESS_TOKEN`.
+- For equivalent multi-language examples, order tabs as JavaScript/Node.js,
+  Python, then cURL. Comparison tabs may follow the order that best teaches the
+  difference.
+- Keep examples fictional and never include or request real credentials.
+
+## Callouts
+
+Use the supported blockquote form:
+
+```markdown
+> [!NOTE] Optional title
+> Supporting content.
+```
+
+- Use `NOTE` for context that affects understanding.
+- Use `TIP` for optional advice or a more effective workflow.
+- Use `WARNING` for credible security, privacy, data-loss, breaking-change, or
+  operational risk.
+- Use sentence case for optional callout titles. Do not use HTML line breaks to
+  separate callout paragraphs.
+
+## Tabs
+
+Use tabs when equivalent examples in multiple languages or a focused comparison
+are easier to understand together:
+
+```markdown
+:::tabs
+@tab JavaScript/Node.js
+JavaScript example
+
+@tab Python
+Python example
+:::
+```
+
+Use an `@tab` label for each panel and close the container with `:::`. For
+equivalent language examples, order tabs as JavaScript/Node.js, Python, then
+cURL. Comparison tabs may use the order that best teaches the difference.
+
+## Links and presentation
+
+- Use canonical documentation paths from `manifest.json`. Keep aliases only for
+  compatibility; do not introduce new links to aliases.
+- Use normal Markdown links for internal navigation. Keep HTML only when it adds
+  behavior Markdown cannot express, such as opening an external link in a new
+  tab.
+- Avoid deeply nested headings, very wide tables, and long unbroken text that is
+  difficult to use in the constrained content column.
+- Remove trailing whitespace and use blank lines, not `<br>`, for Markdown
+  structure unless a verified rendering requirement needs HTML.

package/docs/amounts-and-balances.md

@@ -1,4 +1,4 @@
-# Amounts & Balances
+# Amounts & balances
 
 The Lunch Money API uses four properties — `amount`, `balance`, `currency`, and `to_base` — consistently across all objects that deal with money. Understanding how they work will help you build accurate, multi-currency-aware integrations.
 
@@ -24,7 +24,7 @@ Like `amount`, `balance` is always in the `currency` of the same object and foll
 
 ## `currency`
 
-`currency` is an ISO 4217 currency code (e.g., `"usd"`, `"eur"`, `"gbp"`). It is present on every object that carries an `amount` or `balance` and tells you what currency those values are in. See the [Supported Currencies guide](/v2/currencies) for the full list.
+`currency` is an ISO 4217 currency code (e.g., `"usd"`, `"eur"`, `"gbp"`). It is present on every object that carries an `amount` or `balance` and tells you what currency those values are in. See the [Supported currencies guide](/currencies) for the full list.
 
 ## `to_base`
 
@@ -42,7 +42,7 @@ Like `amount`, `balance` is always in the `currency` of the same object and foll
 - Display amounts and balances in a single consistent currency across a multi-currency account
 - Perform arithmetic across transactions or accounts in different currencies
 
-## Sign Convention
+## Sign convention
 
 ### Transaction amounts
 
@@ -70,10 +70,10 @@ A negative balance indicates the reversed state for that account type:
 - A savings account in overdraft has a negative `balance`
 - A credit card where the issuer owes you money (e.g., after a refund or overpayment) has a negative `balance`
 
-> [!NOTE] App Display Setting
+> [!NOTE] App display setting
 > The Lunch Money app has a setting — **"Show Debits as Negative, Credits as Positive"** — that can flip how amounts are displayed in the UI. This setting is exposed in the API as `debits_as_negative` on the User object. **It has no effect on the API.** The API always returns positive values for debits and negative values for credits regardless of this setting. Apps may read `debits_as_negative` to match the user's preferred display format when showing amounts in their own UI.
 
-## Exception: Budget and Summary Amounts
+## Exception: budget and summary amounts
 
 Budget objects and summary response objects don't use the transaction sign convention. Direction is conveyed by the **structure of the response** rather than the sign of the value — amounts are always positive magnitudes, and the object type or category flag tells you whether that activity is income or expense.
 

package/docs/branding-your-app.md

@@ -1,4 +1,4 @@
-# Branding your App
+# Branding your app
 
 Building a tool, plugin, or integration on top of Lunch Money? Use the official **Powered by Lunch Money** badge to credit the connection clearly — without implying that your app *is* Lunch Money.
 

package/docs/currencies.md

@@ -1,15 +1,15 @@
-# Supported Currencies
+# Supported currencies
 
 Lunch Money supports a wide range of currencies for transactions and accounts. All currency values in the API use three-letter lowercase currency codes in ISO 4217 format.
 
-## Currency Code Format
+## Currency code format
 
 Currency codes must be:
 - Three letters
 - Lowercase
 - Valid ISO 4217 currency codes
 
-## Supported Currencies
+## Supported currencies
 
 The following currencies are currently supported in Lunch Money:
 
@@ -183,7 +183,7 @@ The following currencies are currently supported in Lunch Money:
 | `zmw` | Zambian Kwacha |
 | `zwl` | Zimbabwean Dollar |
 
-## Using Currencies in the API
+## Using currencies in the API
 
 When creating or updating transactions, accounts, or other resources that include currency information, use the three-letter lowercase currency code:
 
@@ -247,11 +247,11 @@ curl -X POST 'https://api.lunchmoney.dev/v2/transactions' \
 ```
 :::
 
-## Default Currency
+## Default currency
 
 If you don't specify a currency when creating a transaction or account, Lunch Money will default to your account's primary currency. You can check your primary currency by calling the `GET /v2/me` endpoint.
 
-## Currency Validation
+## Currency validation
 
 The API validates that currency codes match the supported list. If you provide an unsupported currency code, you'll receive a validation error:
 
@@ -268,10 +268,9 @@ The API validates that currency codes match the supported list. If you provide a
 }
 ```
 
-## Requesting New Currencies
+## Requesting new currencies
 
 If your currency is missing from the supported list, please let us know via email at [support@lunchmoney.app](mailto:support@lunchmoney.app) and we'll work on getting it added.
 
-> [!NOTE] Currency Support
+> [!NOTE] Currency support
 > Currency support is continuously expanding. If you need a currency that's not currently listed, reach out to our support team and we'll prioritize adding it.
-

package/docs/getting-started.md

@@ -1,14 +1,14 @@
-# Getting Started with the API
+# Getting started with the API
 
 Welcome to the Lunch Money developer API! This API has enabled the Lunch Money user community to build a broad set of tools and plug-ins to complement their Lunch Money experience and help other users. This guide will help you get started using the Lunch Money API.
 
 Most users interact with their Lunch Money data using the official web or mobile app. Making API calls is another way to interact with your Lunch Money data. You can make API calls that **get** your data for you, allowing you to do other things with it, like generating your own charts or simply archiving your data. You can also make API calls that **change** or **delete** your data. Any changes you make are permanent, just like they would be if you made changes using the web or mobile app.
 
 > [!WARNING]
-> Changes made via the API are permanent and cannot be undone!<br> Always use a test budget when getting started.
+> Changes made via the API are permanent and cannot be undone. Always use a test budget when getting started.
 
 
-## Create a Test Budgeting Account
+## Create a test budgeting account
 
 Since changes to your data made by the API are permanent, the best way to begin interacting with the API is to <a href="https://support.lunchmoney.app/miscellaneous/unlimited-budgeting-accounts" target="_blank" rel="noopener noreferrer">create a new test budgeting account</a> in your existing Lunch Money account. As you start using the API, you can interact with this test account and ensure that your real data is not modified.
 
@@ -49,7 +49,7 @@ After you do this, the web page will show you a long alphanumeric string. This i
 Congratulations! You've got an access token and are ready to make an API request! Later, when you are more comfortable with the API, you can repeat this process to create a new access token associated with your real budget.
 
 > [!WARNING]
-> Treat your access tokens like passwords.<br>Don't share them with anyone that you don't trust. 
+> Treat your access tokens like passwords. Don't share them with anyone you don't trust.
 
 If you ever worry that your access token has been compromised, you can always come back to the Developers page and hit the Revoke button.
 
@@ -63,21 +63,21 @@ When you start to write code that makes API calls, you will need to include this
 
 ```bash
 curl --location 'https://api.lunchmoney.dev/v2/me' \
---header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'
+--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
 ```
 
-If this doesn't make sense yet, that's OK! 
+If this doesn't make sense yet, that's OK!
 
-There is an easier way to use your access token to make requests. Head over to the [API Reference Documentation](/v2/docs). 
+There is an easier way to use your access token to make requests. Head over to the [API Reference Documentation](/v2/docs).
 
 :::tabs
 
 @tab 1. Supply Your Token
-Paste your new token into the box that says "Bearer Token" in the server configuration in the upper right hand corner. 
+Paste your new token into the box that says "Bearer Token" in the server configuration in the upper right hand corner.
 ![Bearer Token](/images/PasteBearer.png)
 
 @tab 2. Make a Test Request
-Scroll down to the section called "Get Current User" and hit the "Test Request" button. 
+Scroll down to the section called "Get Current User" and hit the "Test Request" button.
 ![TestRequest.png](/images/TestRequest.png)
 :::
 
@@ -85,14 +85,14 @@ This will pop up a dialog box that you can use to send an API request. This is a
 
 From here, you can explore the rest of the Lunch Money API and start thinking about what you might do with it.
 
-## What Can You Build?
+## What can you build?
 
 The Lunch Money community has already built a wide variety of tools — automations, importers, dashboards, and more. Check out the <a href="https://lunchmoney.app/developers#community-projects" target="_blank" rel="noopener noreferrer">Developer Tools & Community Projects</a> list for inspiration, or drop by the <a href="https://discord.com/channels/842337014556262411/1134597088504729780" target="_blank" rel="noopener noreferrer">Show and Tell channel</a> on Discord to see what others are sharing.
 
 > [!NOTE]
 > Built something with the API? Let us know and we'll add it to the list!
 
-## I still need help!
+## Need help?
 
 If you still aren't sure how to get started, we have other resources to help.
 

package/docs/introduction.md

@@ -2,7 +2,7 @@
 
 Welcome to the Lunch Money developer documentation. This site covers the **v2 API** — the current generation of the Lunch Money API — along with guides, a reference for the legacy v1 API, and tools for exploring the API without touching real data.
 
-## Getting Started
+## Getting started
 
 The v2 API is available at:
 
@@ -16,9 +16,9 @@ Get your access token from the <a href="https://my.lunchmoney.app/developers" ta
 Authorization: Bearer YOUR_ACCESS_TOKEN
 ```
 
-See the [Getting Started guide](/v2/getting-started) for a full walkthrough, including how to create a test budget and make your first request.
+See the [Getting started guide](/getting-started) for a full walkthrough, including how to create a test budget and make your first request.
 
-## Trying the API Without Real Data
+## Trying the API without real data
 
 The <a href="/v2/docs">interactive API reference</a> lets you make live API requests directly from the documentation — including a **static mock server** you can use to explore the API without an access token or any risk to real data.
 
@@ -34,7 +34,7 @@ Set your Bearer Token to any string of **11 or more characters** — no real tok
 
 :::
 
-## Client Libraries & SDKs
+## Client libraries & SDKs
 
 An official **TypeScript SDK** is available:
 - NPM: <a href="https://www.npmjs.com/package/@lunch-money/v2-api-spec" target="_blank" rel="noopener noreferrer">`@lunch-money/v2-api-spec`</a>
@@ -58,6 +58,6 @@ Join the conversation in the <a href="https://lunchmoney.app/discord" target="_b
 
 **Useful links:**
 - <a href="/v2/docs">Interactive API Reference</a>
-- [Getting Started Guide](/v2/getting-started)
+- [Getting started guide](/getting-started)
 - <a href="https://github.com/lunch-money/awesome-lunchmoney" target="_blank" rel="noopener noreferrer">Awesome Lunch Money Projects</a>
 - [Contact: devsupport@lunchmoney.app](mailto:devsupport@lunchmoney.app)

package/docs/locales.md

@@ -1,4 +1,4 @@
-# Supported Locales
+# Supported locales
 
 Lunch Money uses locale tags to format numbers and currency amounts in the web
 and mobile apps. Date presentation is controlled separately by the user-level
@@ -10,14 +10,14 @@ currency symbol or code placement and rendering. It does not change the
 account's selected currency, numeric values, or the representation of dates,
 numbers, and amounts in API responses.
 
-## Locale Tag Format
+## Locale tag format
 
 Each supported value combines a language code and a region code, separated by a
 hyphen. For example, `en-US` selects English formatting conventions for the
 United States, while `en-GB` selects English formatting conventions for the
 United Kingdom.
 
-## Supported Locales
+## Supported locales
 
 The examples format `123456789` as USD. An account's primary currency determines
 the currency symbol and number of fraction digits. Exact spacing and symbol
@@ -111,7 +111,7 @@ implementation.
 | `uk-UA` | Ukrainian | Ukraine | `123 456 789,00 USD` |
 | `vi-VN` | Vietnamese | Vietnam | `123.456.789,00 US$` |
 
-## Legacy Locale Tags
+## Legacy locale tags
 
 The supported list retains two legacy language codes for compatibility:
 

package/docs/oauth/authorization-code.md

@@ -0,0 +1,80 @@
+# Implement the authorization-code flow
+
+After you [register an OAuth client](/oauth/register-client), your application uses its settings—including its client ID, client secret, and registered redirect URI—to implement the authorization flow. As shown in the [OAuth overview](/oauth), your application sends the user to Lunch Money, Lunch Money returns an authorization code to your callback, and your application exchanges that code for tokens.
+
+This guide walks through that process for a **Confidential web client**. Your server handles the callback and token exchange and keeps the client secret and refresh tokens secure. If you are building a standalone mobile or desktop application, read the [native application guidance](/oauth/native-apps) instead.
+
+## Choose an OAuth library
+
+OAuth libraries handle much of the protocol work for you, including generating PKCE values, building authorization requests, validating callback state, and exchanging authorization codes. Choose a well-maintained OAuth 2.0 client library for your language and application framework. Look for support for:
+
+- the authorization-code flow with Proof Key for Code Exchange (PKCE);
+- OAuth authorization-server metadata discovery;
+- secure `state` generation and validation; and
+- confidential-client authentication with HTTP Basic.
+
+For Node.js and TypeScript, [`openid-client`](https://github.com/panva/openid-client) is one maintained option. Despite its name, using it does not mean that Lunch Money supports OpenID Connect identity scopes, ID tokens, or UserInfo.
+
+## Configure Lunch Money with discovery
+
+Your OAuth library needs to know where to send the user for authorization, where to exchange codes for tokens, and which protocol features Lunch Money supports. Instead of configuring each value separately, give the library the Lunch Money issuer:
+
+`https://api.lunchmoney.dev`
+
+Then have it load the OAuth authorization-server metadata document:
+
+`https://api.lunchmoney.dev/.well-known/oauth-authorization-server`
+
+The metadata document is a machine-readable description of Lunch Money's authorization, token, and revocation endpoints, supported client-authentication methods, and PKCE method. Using it allows your library to obtain the current OAuth configuration without your application assembling endpoint URLs itself.
+
+> [!TIP]
+> The resolved endpoint paths are `/oauth/authorize`, `/oauth/token`, and `/oauth/revoke`. These are useful when debugging, but use metadata discovery when your library supports it.
+
+## 1. Start authorization
+
+On your server, generate:
+
+- a cryptographically random `state` value bound to the user's session;
+- a PKCE `code_verifier`; and
+- its `S256` `code_challenge`.
+
+Redirect the browser to the discovered authorization endpoint with `response_type=code`, your `client_id`, exact `redirect_uri`, `state`, `code_challenge`, and `code_challenge_method=S256`.
+
+> [!NOTE] Scopes come from the client registration
+> You do not need to send `scope`. If your OAuth library includes it, Lunch Money ignores the requested value and uses the client's complete registered scope set. An authorization request cannot narrow or expand that set; changing scopes requires a replacement client.
+
+## 2. Handle the callback
+
+The callback receives either `code` and `state`, or an OAuth `error` and the original `state`. Before exchanging a code:
+
+1. compare `state` with the one-time value stored in the initiating session;
+2. reject missing, mismatched, or reused state;
+3. reject unexpected issuer or callback parameters;
+4. consume the stored state and PKCE verifier once; and
+5. remove authorization parameters from the visible browser URL before rendering a page.
+
+Treat `access_denied` as a normal user decision. Do not log the callback query string.
+
+## 3. Exchange the code
+
+Send a form-encoded request to the discovered token endpoint with `grant_type=authorization_code`, the code, exact `redirect_uri`, and original `code_verifier`. A confidential client authenticates with HTTP Basic using its client ID and secret. Do this server-side.
+
+Store `access_token`, `token_type`, granted `scope`, and expiration metadata securely. If a `refresh_token` is returned, keep it server-side as a high-value credential.
+
+## 4. Call the API
+
+Send the access token in the header:
+
+```http
+GET /v2/me HTTP/1.1
+Host: api.lunchmoney.dev
+Authorization: Bearer YOUR_ACCESS_TOKEN
+```
+
+The operation must be allowed by the token's scope and by the user's access to the selected budgeting account. See the [scope catalog](/oauth/scopes).
+
+## 5. Continue or recover
+
+Use the response's `expires_in` value to schedule renewal slightly before expiry. Read [token lifecycle and recovery](/oauth/tokens) before implementing refresh, logout, or revocation.
+
+Next: [Develop and test your OAuth application](/oauth/development).

package/docs/oauth/concepts.md

@@ -0,0 +1,46 @@
+# OAuth concepts
+
+These terms describe who participates in Lunch Money OAuth and what each credential can do.
+
+## Parties in the flow
+
+- **User (resource owner):** the Lunch Money user who authorizes a third-party application to make API requests on their behalf for one budgeting account.
+- **Application:** the complete product or service the developer builds. It may contain many features unrelated to Lunch Money; only its Lunch Money OAuth client is managed in the Developer Portal.
+- **Client:** the application's OAuth registration with Lunch Money: its `client_id`, type, redirect URIs, selected scopes, and—when applicable—client secret. The developer must register this client in the Developer Portal before the application can ask Lunch Money users to authorize API access.
+- **Authorization server:** the Lunch Money-owned service that presents the Lunch Money sign-in and consent screens, records the user's decision, and issues authorization codes and tokens. The user signs in directly with Lunch Money; the third-party application never receives or sees their Lunch Money login credentials.
+- **Lunch Money API service:** the Lunch Money-owned V2 API, which receives the application's API requests, accepts access tokens, and checks that each request is permitted by the client's scopes.
+
+## Client types and credentials
+
+When a developer registers a client, they must choose a client type based on whether the application code can keep a client secret secure. This choice cannot be changed after the client is registered. The developer selects either **Confidential web client** or **Native or public client**.
+
+- **Confidential web client:** Runs on a server and can securely store client secrets. In OAuth terminology, this is called a *confidential client*. Choose this type for a web application—or any other application architecture with a centralized server. Its client secret helps Lunch Money verify that a token request came from the application that registered the client. The client secret and refresh tokens must stay on the server. The application must protect access tokens wherever its architecture uses them, and associate each authorization with the correct application user and authorized Lunch Money budgeting account.
+- **Native or public client:** Runs on a user-controlled device and uses PKCE without a client secret because installed application code cannot keep a secret secure. In OAuth terminology, this is called a *native public client*. Choose this type for a standalone mobile or desktop application. The app stores each user's tokens securely on that user's device—for example, in Keychain on Apple platforms or appropriate Keystore-backed storage on Android—and must avoid exposing them through backups, logs, or application data shared with other apps.
+
+Every client receives a client ID that identifies its Lunch Money registration. The client ID is not secret. Both client types also use Proof Key for Code Exchange (PKCE) to bind the authorization response to the application that started the flow.
+
+## Redirect URIs
+
+A redirect URI is the callback address where the Lunch Money authorization server returns control to the application after the user approves or denies access. Lunch Money redirects the user's browser to that address with either a temporary authorization code or information about why authorization did not complete.
+
+The developer registers each permitted redirect URI in advance. For a confidential web client, the URI sent at the start of authorization must exactly match one of those registered values, including its scheme, host, port, path, and query string. A native client's loopback redirect follows the same rule except that its ephemeral port is ignored. Fragments are not allowed. These checks prevent an authorization result from being redirected to an unexpected destination. The application's callback must also avoid acting as an open redirect to another location.
+
+## Scopes and least privilege
+
+Resource scopes such as `transactions:read` authorize specific ways of working with Lunch Money data. A scope generally applies to a particular kind of action—such as reading or updating a resource—and only to the relevant API endpoints. Permissions are independent: for example, `transactions:update` does not also grant `transactions:read`.
+
+The [V2 API reference](/v2/docs) identifies the scope required by each API endpoint. Use it together with the [scope catalog](/oauth/scopes) to select the permissions your application's features require.
+
+Scopes are selected when the client is created and cannot be edited later. Every user who authorizes that client sees and grants all—and only—the scopes the developer selected. To change them, create and test a replacement client, complete review when applicable, update your integration, and ask existing users to authorize again. Existing authorizations and tokens do not move to the replacement client.
+
+Select `offline_access` when your application needs to continue making API requests on a user's behalf for longer than the brief period covered by the initial access token. It allows the application to receive a refresh token, which it can use to maintain access without repeatedly asking the user to sign in and authorize the application. It does not add permission to read or change any Lunch Money data; the client still needs the relevant resource scopes.
+
+## Codes and tokens
+
+- An **authorization code** is the short-lived, single-use value Lunch Money sends to the application's callback after the user approves access. The code cannot make API requests by itself. Every client exchanges it at Lunch Money's token endpoint using its PKCE verifier. A confidential client must also authenticate that request with its client ID and client secret. Lunch Money then returns an access token and, when applicable, a refresh token.
+- An **access token** is a credential the application sends as part of each V2 API request. It is relatively short-lived. The token response includes `expires_in`, the number of seconds for which the access token is expected to remain valid, so the application can record when it will expire and obtain a replacement when needed.
+- A **refresh token** is a longer-lived but non-permanent credential available only to clients that selected `offline_access`. The application sends it to Lunch Money's token endpoint to request a new access token and replacement refresh token without asking the user to authorize again.
+
+An application can refresh its access token shortly before it expires or wait until an API response indicates that the access token is no longer valid. If the application does not have a refresh token—or if that token expires, is revoked, or otherwise stops working—it must ask the user to authorize again.
+
+Next: [Register an OAuth client](/oauth/register-client).

package/docs/oauth/development.md

@@ -0,0 +1,57 @@
+# Develop and test an OAuth application
+
+Use this guide after you have [registered a client](/oauth/register-client) and implemented the [authorization flow](/oauth/authorization-code). At this stage, your application should be able to send its owner to Lunch Money, receive an authorization code at its callback, exchange the code for tokens, and make an API request.
+
+The goal now is to test that complete workflow—including its failure and recovery paths—before asking Lunch Money to approve the application for other users.
+
+> [!NOTE] Development access is owner-only
+> While an OAuth client is in development, only the Lunch Money user who owns it can authorize the application. Your team should have the developer doing most of the initial Lunch Money work create and own the client so they can test the complete flow with their budgeting accounts. Other team members cannot authorize the application until the client has been reviewed and approved.
+
+## Set up a safe test environment
+
+Use a separate Lunch Money test budgeting account when exercising create, update, or delete operations. The [Getting Started guide](/getting-started#create-a-test-budgeting-account) walks through creating one and adding sample data.
+
+Keep production client secrets, tokens, and user data out of test fixtures, logs, screenshots, and bug reports.
+
+## Local loopback callbacks
+
+When you run a confidential web application on your own computer, its callback handler may not have a public HTTPS address yet. A loopback redirect lets the browser return the authorization result directly to the local process you are developing.
+
+For a client in development, register an HTTP redirect using a supported loopback host and the port and path where your application listens:
+
+- Hostname: `http://localhost:43821/callback`
+- IPv4: `http://127.0.0.1:43821/callback`
+- IPv6: `http://[::1]:43821/callback`
+
+You may choose any available port, but the complete redirect URI sent during authorization must match the registered value exactly. `localhost` and `127.0.0.1` are different hosts, so register the form your application sends. Non-loopback HTTP hosts, embedded credentials, and URI fragments are not supported.
+
+The user's browser—not Lunch Money's server—connects to the loopback listener. Keep PKCE and `state` protections in place just as you would for a hosted callback. Before requesting review, also register the HTTPS callback used by the deployed application; the loopback URI can remain available for local testing.
+
+> [!NOTE] Test an approved client with your development team
+> After a client is approved, other team members can continue developing and testing the application's Lunch Money functionality. If the approved client has a loopback redirect registered, each developer who can run the application locally may authorize access to their own Lunch Money budgeting account. The client ID is public, but developers working on a confidential web client also need access to its client secret through your team's secure credential-management process. Do not share access tokens or refresh tokens between developers.
+
+## Repeat or reset authorization
+
+During development, the client owner can run authorization again whenever they want to repeat the sign-in, budgeting-account selection, consent, and callback flow. They do not need to revoke the current token first; a new successful authorization replaces their previous active authorization for that client.
+
+To test how the application responds after access is revoked, revoke the current token and make another API request with it. Lunch Money should reject the request, and the application should discard its saved credentials and begin authorization again. The [token revocation guide](/oauth/tokens#revoke-access) includes copyable `curl` requests for development testing.
+
+## Test the complete client
+
+1. Complete authorization. For each attempt, your application should create a random `state` value, save it with the application user's session, and verify that Lunch Money returns the same value to the callback. Rejecting a missing, changed, or reused value prevents a callback started elsewhere from being attached to the wrong session.
+2. Keep the PKCE verifier with that same authorization attempt and use it when exchanging the returned code. Confirm that an exchange with a missing or changed verifier fails; this prevents someone who intercepts the code from using it.
+3. Read the token response's `scope` field and confirm that it contains the complete scope set registered for the client. Do not inspect or parse the access token itself.
+4. Call every scope-dependent feature, including negative permission cases.
+5. Test user denial, missing or changed `state`, callback errors, and interrupted authorization attempts.
+
+## Test reauthorization before refresh
+
+First make sure your application can recover without a refresh token. Record when the token response arrives and use `expires_in` to determine when the access token is expected to expire. After it expires, make a harmless API request and confirm that Lunch Money returns an authentication failure identifying the token as invalid.
+
+Your application should discard the unusable token and start authorization again. Confirm that the same application user can complete the flow, select a budgeting account, and continue using the application with the replacement token. This recovery path is required when a client does not have `offline_access`, and it remains the fallback when a refresh token expires, is revoked, or otherwise stops working.
+
+After reauthorization works, clients registered with `offline_access` can add and test refresh-token handling. Verify replacement-token storage, concurrent-refresh protection, revocation, and terminal refresh recovery before relying on unattended operation. See [token lifecycle and recovery](/oauth/tokens).
+
+Finally, add a production HTTPS redirect and complete the [review checklist](/oauth/review-and-approval).
+
+Next: [Operate securely](/oauth/security).

package/docs/oauth/index.md

@@ -0,0 +1,28 @@
+# OAuth for Lunch Money integrations
+
+OAuth lets your application access Lunch Money on behalf of a user without asking that person to copy and share a personal access token. **If you are building an application for anyone other than yourself, use OAuth.** It gives each user a familiar Lunch Money sign-in and consent experience while keeping their personal access token out of your application.
+
+![OAuth authorization-code flow across your application, the Lunch Money user, and Lunch Money. The application redirects the user's browser, Lunch Money handles sign-in and presents the budgeting-account and permission choices, the user approves access, Lunch Money returns an authorization code, and the application exchanges it for tokens and calls the API.](/v2/images/oauth-authorization-flow.svg)
+
+## Choose OAuth or a personal access token
+
+| Question | Personal access token | OAuth application and client |
+| --- | --- | --- |
+| Whose data can it access? | One budgeting account belonging to the user who created the token | One budgeting account selected by each user who authorizes the application |
+| Best fit | API exploration, one-off scripts, and short-lived work on your own account | Persistent integrations and applications intended for other users |
+| How is access granted? | The user creates a token on the [Developers page](https://my.lunchmoney.app/developers) in the Lunch Money web app | The user signs in and approves the permissions requested by the application |
+| Credential handling | The user keeps the token and sends it with their own API requests; third-party applications should use OAuth instead of asking users to share one | The authorization flow delivers application-specific tokens without asking for a personal token |
+| Permissions | Full access to the Lunch Money APIs available for that budgeting account, with no fine-grained permission controls | Only the permissions selected when the application was created |
+| Lifecycle | Created and revoked by the user | Short-lived access tokens and optional finite refresh access; the user can revoke the application's access |
+
+Personal access tokens remain useful for quick work on your own account. OAuth is the recommended model for applications and integrations that other Lunch Money users will connect to, as well as automations that need to run over time.
+
+## What limits access
+
+When a developer creates an OAuth application, they select the scopes—the specific permissions—the application needs. Later, when a Lunch Money user authorizes the application, Lunch Money shows them that complete permission set before they approve access. Choose only the permissions the application's features require. A focused permission request is easier for users to understand and trust, and reduces the risk of the application reading or changing data it does not need.
+
+## Before you start
+
+You need an active Lunch Money account to [register and manage an OAuth application](/oauth/applications). During development, only the application owner can authorize it. Approval is required before other Lunch Money users can authorize it.
+
+Start with [OAuth concepts](/oauth/concepts), [register a client](/oauth/register-client), and then [implement the authorization-code flow](/oauth/authorization-code). Use the [scope catalog](/oauth/scopes) to plan permissions and [troubleshooting](/oauth/troubleshooting) when a flow fails.

package/docs/oauth/native-apps.md

@@ -0,0 +1,26 @@
+# OAuth for native iOS and Android apps
+
+Native apps are public clients: they cannot keep a client secret. Use authorization code with PKCE and launch Lunch Money sign-in and consent in a trusted platform authentication browser—not an embedded WebView.
+
+## Recommended libraries
+
+- iOS and macOS: [`AppAuth-iOS`](https://github.com/openid/AppAuth-iOS), presented through `ASWebAuthenticationSession`.
+- Android: [`AppAuth-Android`](https://github.com/openid/AppAuth-Android), which uses a browser Custom Tab.
+- Bare or non-Expo React Native: [`react-native-app-auth`](https://github.com/FormidableLabs/react-native-app-auth).
+- Expo: Use [`expo-auth-session`](https://docs.expo.dev/versions/latest/sdk/auth-session/) for browser-based OAuth flows.
+
+Use Lunch Money's authorization-server discovery document and configure `token_endpoint_auth_method=none`. Send the client ID at the token and revocation endpoints, but never invent or embed a client secret. You do not need to configure authorization-request scopes because the registered client receives its complete fixed set. If your OAuth library sends `scope`, Lunch Money ignores that value and uses the registered set.
+
+## Redirects
+
+Use a redirect mechanism that returns control to your app and that your platform can bind to it. Claimed Universal Links or Android App Links provide stronger app ownership than a custom URI scheme when correctly configured. Custom schemes must be distinctive and protected against interception.
+
+The loopback callbacks supported for confidential web development do not define native or desktop redirect support. Follow the native redirect choices accepted during client registration; do not assume the confidential web-client loopback rules apply.
+
+## Store and renew tokens
+
+Store tokens in Keychain on Apple platforms. On Android, use current Keystore-backed storage guidance from your maintained library; do not start new work with deprecated `EncryptedSharedPreferences` APIs. Coordinate refresh-token use, persist replacements, and fall back to interactive authorization after terminal failure.
+
+Platform code should delegate protocol validation to the maintained library while your application supplies safe configuration, lifecycle storage, API calls, revocation, and user-facing recovery. Full Lunch Money Swift and Kotlin sample apps are not part of this documentation phase; the upstream AppAuth projects provide maintained platform examples.
+
+Next: [Review OAuth security guidance](/oauth/security).