Develop and test an OAuth application

Use this guide after you have registered a client and implemented the authorization flow. 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.

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 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.

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 includes copyable curl requests for development testing.

Test the complete client

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.
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.
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.
Call every scope-dependent feature, including negative permission cases.
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.

Finally, add a production HTTPS redirect and complete the review checklist.

Next: Operate securely.