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 identifies the scope required by each API endpoint. Use it together with the scope catalog 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.