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

package/docs/oauth/tokens.md

@@ -0,0 +1,66 @@
+# 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

@@ -0,0 +1,132 @@
+# 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/docs/pagination.md

@@ -6,10 +6,10 @@ The Lunch Money API uses offset-based pagination for the `GET /transactions` end
 
 When retrieving transactions using `GET /transactions`, the API supports pagination through the `limit` and `offset` query parameters. By default, the endpoint returns up to 1000 transactions per request. If more transactions match your filter criteria, the response includes a `has_more` property set to `true`, indicating that additional pages are available.
 
-> [!NOTE] Pagination Scope
+> [!NOTE] Pagination scope
 > Pagination works with all filter parameters including date ranges, account IDs, categories, tags, and status filters. The pagination applies to the filtered result set.
 
-## How Pagination Works
+## How pagination works
 
 ### Parameters
 
@@ -24,13 +24,13 @@ When retrieving transactions using `GET /transactions`, the API supports paginat
   - Minimum: `0`
   - Use this to fetch subsequent pages of results
 
-### Response Property
+### Response property
 
 - **`has_more`**: A boolean property in the response indicating whether more transactions are available
   - `true`: More transactions match your filter criteria and are available on subsequent pages
   - `false`: All matching transactions have been returned
 
-### Basic Pagination Flow
+### Basic pagination flow
 
 1. Make your first request (optionally with `limit` specified, defaults to 1000)
 2. Check the `has_more` property in the response
@@ -39,7 +39,7 @@ When retrieving transactions using `GET /transactions`, the API supports paginat
 
 ## Examples
 
-### Basic Pagination
+### Basic pagination
 
 Here's how to fetch transactions page by page:
 
@@ -61,10 +61,10 @@ async function getAllTransactions(accessToken, limit = 1000) {
 
     const data = await response.json();
     allTransactions.push(...data.transactions);
-    
+
     hasMore = data.has_more;
     offset += limit;
-    
+
     console.log(`Fetched ${data.transactions.length} transactions (total: ${allTransactions.length})`);
   }
 
@@ -84,22 +84,22 @@ def get_all_transactions(access_token, limit=1000):
     all_transactions = []
     offset = 0
     has_more = True
-    
+
     headers = {
         'Authorization': f'Bearer {access_token}'
     }
-    
+
     while has_more:
         url = f'https://api.lunchmoney.dev/v2/transactions?limit={limit}&offset={offset}'
         response = requests.get(url, headers=headers)
         data = response.json()
-        
+
         all_transactions.extend(data['transactions'])
         has_more = data['has_more']
         offset += limit
-        
+
         print(f"Fetched {len(data['transactions'])} transactions (total: {len(all_transactions)})")
-    
+
     return all_transactions
 
 # Usage
@@ -119,18 +119,18 @@ ALL_TRANSACTIONS="[]"
 
 while [ "$HAS_MORE" = "true" ]; do
   echo "Fetching transactions with offset=$OFFSET, limit=$LIMIT..."
-  
+
   RESPONSE=$(curl -s -X GET \
     "https://api.lunchmoney.dev/v2/transactions?limit=$LIMIT&offset=$OFFSET" \
     -H "Authorization: Bearer $ACCESS_TOKEN")
-  
+
   TRANSACTIONS=$(echo $RESPONSE | jq -r '.transactions')
   HAS_MORE=$(echo $RESPONSE | jq -r '.has_more')
-  
+
   # Merge transactions (simplified - in practice you'd want proper JSON merging)
   COUNT=$(echo $TRANSACTIONS | jq 'length')
   echo "Fetched $COUNT transactions"
-  
+
   OFFSET=$((OFFSET + LIMIT))
 done
 
@@ -138,7 +138,7 @@ echo "All transactions fetched"
 ```
 :::
 
-### Pagination with Date Filters
+### Pagination with date filters
 
 Pagination works seamlessly with date range filters:
 
@@ -166,7 +166,7 @@ async function getTransactionsByDateRange(accessToken, startDate, endDate) {
 
     const data = await response.json();
     allTransactions.push(...data.transactions);
-    
+
     hasMore = data.has_more;
     offset += limit;
   }
@@ -192,9 +192,9 @@ def get_transactions_by_date_range(access_token, start_date, end_date):
     offset = 0
     has_more = True
     limit = 1000
-    
+
     headers = {'Authorization': f'Bearer {access_token}'}
-    
+
     while has_more:
         params = {
             'start_date': start_date,
@@ -202,15 +202,15 @@ def get_transactions_by_date_range(access_token, start_date, end_date):
             'limit': limit,
             'offset': offset
         }
-        
+
         url = f"https://api.lunchmoney.dev/v2/transactions?{urlencode(params)}"
         response = requests.get(url, headers=headers)
         data = response.json()
-        
+
         all_transactions.extend(data['transactions'])
         has_more = data['has_more']
         offset += limit
-    
+
     return all_transactions
 
 # Usage: Get all transactions for January 2024
@@ -236,17 +236,17 @@ while [ "$HAS_MORE" = "true" ]; do
   RESPONSE=$(curl -s -X GET \
     "https://api.lunchmoney.dev/v2/transactions?start_date=$START_DATE&end_date=$END_DATE&limit=$LIMIT&offset=$OFFSET" \
     -H "Authorization: Bearer $ACCESS_TOKEN")
-  
+
   HAS_MORE=$(echo $RESPONSE | jq -r '.has_more')
   COUNT=$(echo $RESPONSE | jq -r '.transactions | length')
   echo "Fetched $COUNT transactions (offset=$OFFSET)"
-  
+
   OFFSET=$((OFFSET + LIMIT))
 done
 ```
 :::
 
-### Handling the `has_more` Flag
+### Handling the `has_more` flag
 
 Always check the `has_more` property to determine if you need to fetch more pages:
 
@@ -262,7 +262,7 @@ async function fetchTransactionsPage(accessToken, limit = 1000, offset = 0) {
   });
 
   const data = await response.json();
-  
+
   return {
     transactions: data.transactions,
     hasMore: data.has_more,
@@ -288,10 +288,10 @@ import requests
 def fetch_transactions_page(access_token, limit=1000, offset=0):
     url = f'https://api.lunchmoney.dev/v2/transactions?limit={limit}&offset={offset}'
     headers = {'Authorization': f'Bearer {access_token}'}
-    
+
     response = requests.get(url, headers=headers)
     data = response.json()
-    
+
     return {
         'transactions': data['transactions'],
         'has_more': data['has_more'],
@@ -335,9 +335,9 @@ fi
 ```
 :::
 
-## Best Practices
+## Best practices
 
-### 1. Use Appropriate Limit Values
+### 1. Use appropriate limit values
 
 Choose a `limit` value that balances performance and number of requests:
 
@@ -353,7 +353,7 @@ const response = await fetch('/v2/transactions?limit=1000');
 const response = await fetch('/v2/transactions?limit=500');
 ```
 
-### 2. Always Check `has_more`
+### 2. Always check `has_more`
 
 Don't assume you've received all results. Always check the `has_more` property:
 
@@ -375,7 +375,7 @@ while (hasMore) {
 }
 ```
 
-### 3. Combine with Date Ranges When Possible
+### 3. Combine with date ranges when possible
 
 If you know the date range you need, use `start_date` and `end_date` parameters to reduce the result set size:
 
@@ -387,12 +387,12 @@ const response = await fetch(
 
 // ❌ Less efficient: Fetches all transactions then filters client-side
 const allTransactions = await fetchAllTransactions();
-const janTransactions = allTransactions.filter(t => 
+const janTransactions = allTransactions.filter(t =>
   t.date >= '2024-01-01' && t.date <= '2024-01-31'
 );
 ```
 
-### 4. Handle Edge Cases
+### 4. Handle edge cases
 
 - **Empty results**: The `transactions` array will be empty, and `has_more` will be `false`
 - **Exact page boundary**: If the number of results is exactly divisible by your limit, `has_more` will be `false` on the last page
@@ -406,24 +406,24 @@ async function safeFetchTransactions(accessToken, limit = 1000, offset = 0) {
       headers: { 'Authorization': `Bearer ${accessToken}` }
     }
   );
-  
+
   if (!response.ok) {
     throw new Error(`API error: ${response.status}`);
   }
-  
+
   const data = await response.json();
-  
+
   // Handle empty results
   if (data.transactions.length === 0 && !data.has_more) {
     console.log('No transactions found');
     return [];
   }
-  
+
   return data;
 }
 ```
 
-### 5. Implement Rate Limit Awareness
+### 5. Implement rate limit awareness
 
 When paginating through many pages, be mindful of rate limits. Consider adding delays between requests:
 
@@ -439,7 +439,7 @@ async function getAllTransactionsWithRateLimit(accessToken) {
     allTransactions.push(...data.transactions);
     hasMore = data.has_more;
     offset += limit;
-    
+
     // Small delay to avoid hitting rate limits
     if (hasMore) {
       await new Promise(resolve => setTimeout(resolve, 100));
@@ -452,7 +452,7 @@ async function getAllTransactionsWithRateLimit(accessToken) {
 
 ## Troubleshooting
 
-### Common Issues
+### Common issues
 
 **Issue**: Getting duplicate transactions across pages
 
@@ -506,7 +506,7 @@ const data = await fetch('/v2/transactions?start_date=2024-01-01&end_date=2024-0
 // data.transactions.length might be 200, and has_more will be false
 ```
 
-## Need Help?
+## Need help?
 
 If you're experiencing pagination issues that can't be resolved through the techniques described above:
 
@@ -514,4 +514,3 @@ If you're experiencing pagination issues that can't be resolved through the tech
 - Verify that you're checking the `has_more` property on each response
 - Consider using date range filters to reduce the result set size
 - [Email our developer advocate](mailto:jp@lunchmoney.app) if you need assistance with pagination implementation
-