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 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 and troubleshoot failures.