Register an OAuth client

Before you add OAuth to your application code, register an OAuth client with Lunch Money. The client identifies your application during authorization and tells Lunch Money who is requesting access, where to return the user, and which permissions the application needs.

Register a new OAuth client in the Developer Portal when you are ready to begin.

Plan the permissions

List the Lunch Money features your application will provide, then use the scope catalog to choose the smallest complete set of permissions those features require. Select offline_access only if the application needs to continue making API requests after the initial access token expires and while the user is away.

If your application may support more than one Lunch Money user or budget account, always include me:read. After authorization, GET /v2/me lets your application record both the Lunch Money user's id and the selected budget account's account_id, then store the connection under the complete application-owner and Lunch Money user/account identity. The same scope is also required when your application only needs to identify one connected budget account.

Scopes cannot be changed after registration. While you are developing your application, creating a replacement client is inexpensive, so let the scope set evolve as you learn what the application needs. Aim to have the application's core functionality—and its required permissions—settled before you submit the client for review.

If functionality added after launch needs a scope that is not already registered, you must register a replacement client with the new complete scope set and have it reviewed before rollout. Existing authorizations do not transfer to the replacement client, so users must authorize it before they can use the new functionality. Treat that reauthorization as part of the feature launch: explain what the application can now do with their Lunch Money data and invite them to authorize the replacement client when they want to enable it.

Choose the client type

Select the type based on whether your application code can keep a client secret secure:

• Confidential web client: Choose this when a trusted server can store a client secret, including for applications that are not traditional websites but use a centralized server.
• Native or public client: Choose this for standalone applications installed on a user-controlled device. These clients use PKCE without a client secret. Review the native application guidance before choosing redirects for this type.

The client type cannot be changed after registration. See OAuth concepts for more detail about the two types.

Register redirect URIs

A redirect URI tells Lunch Money where to return the user after authorization. Register every callback address your application will use. Confidential web clients must match every component of a registered URI, including its scheme, host, port, path, and query string. Native-client loopback redirects use the same exact matching except that the ephemeral port is ignored.

Web applications normally use an HTTPS callback. If you need a callback for local development, review the loopback guidance before registering one. Mobile and desktop applications may use a private-use scheme containing a dot, such as app.example.demo:/oauth/callback, or a verified HTTPS link accepted by the Developer Portal.

After the client is approved, you can add or replace redirect URIs in the Developer Portal without submitting another initial review. An approved confidential web client must keep a production HTTPS callback. See after approval.

Each client can have up to 10 redirect URIs, and each URI can be up to 2,048 characters. If you reach the limit, remove a callback the application no longer uses before adding another.

Register the OAuth client

Open the new OAuth client form in the Developer Portal. Then:

1. Describe the application so Lunch Money users can understand who built it and what it does.
2. Provide a monitored support email where users can reach you if authorization fails.
3. Choose its client type.
4. Add at least one redirect URI.
5. Select the planned scopes.
6. Accept the current Lunch Money API Terms of Use and select Register OAuth client.

You can own up to 25 non-deleted OAuth clients. If you reach the limit, delete a client you no longer use before registering another.

After registration, record the client ID in your application configuration. A client ID identifies the registration but is not a secret.

If you registered a Confidential web client, create a client secret from its details page. Lunch Money shows the secret value only once. Copy it immediately into a secret manager or protected server configuration; it cannot be retrieved later. Never commit it or expose it in browser or mobile code.

A confidential web client can have up to three non-revoked secrets. This allows you to introduce a replacement secret, update and verify the deployed application, and then revoke the old secret without interrupting authorization. Expired secrets still count toward the limit until you revoke them. Revoking an obsolete secret frees a slot, and revoked secrets no longer appear in the client's secret list. See OAuth security guidance when planning ongoing rotation.

You now have the client settings needed to connect your application to Lunch Money.

To exercise those settings with a focused confidential-client implementation, try OAuth with the Node.js sample.

Next: Implement authorization.