Setting the redirect URL

The redirect URI is the URL that receives the authorization code after the user presses "Allow" on the authorization screen in the OAuth flow. The URI you register at app registration and the redirect_uri you specify when actually sending a request to /oauth/authorize must match exactly.

The role of the redirect URI

In the OAuth authorization code flow, the values are passed in the following order.

1. The app sends the user to ReceiptRoller's authorization screen (including redirect_uri)
2. The user presses "Allow"
3. ReceiptRoller redirects to the registered redirect URI with a code parameter
4. The app obtains an access token using the code

If you specify a redirect URI that is not registered, or one that differs by even a single character from the registered value, ReceiptRoller does not return an authorization code and instead returns an invalid_redirect_uri error. This is a mechanism to prevent an attacker from stealing the code.

Registration rules

Using development vs. production environments

Many apps have multiple environments: "development", "staging", "production". On ReceiptRoller you can register multiple redirect URIs per app, so adding a URI per environment is the basic approach.

Recommended pattern

https://app.example.com/oauth/callback           ← production
https://staging.example.com/oauth/callback       ← staging
http://localhost:3000/oauth/callback             ← development (local)

You can also separate apps by environment, but we strongly recommend always separating the production app from the development app. The reasons are as follows.

• You no longer need to distribute the production client secret to every developer
• You prevent accidents where a development-time glitch mistakenly invalidates production users' tokens
• User-scope review completes for the production app alone

Registration procedure

1. Developer portal → app list → open the target app
2. Click the "+ Add" button in the "Redirect URI" section
3. Enter the URI and "Save"
4. Repeat for as many environments as needed

Registered URIs take effect immediately. No rebuild or redeploy of the app is needed.

Leveraging the state parameter

Pass dynamic information (the URL of the page you came from, the user ID, a CSRF token, etc.) via the state parameter rather than embedding it directly in the redirect URI. ReceiptRoller returns state as-is after authorization, so you can restore it on the callback side.

// Authorization request
https://receiptroller.io/oauth/authorize
  ?client_id=xxx
  &redirect_uri=https://app.example.com/oauth/callback
  &state=eyJjc3JmIjoiYWJjMTIzIiwicmV0dXJuIjoiL2Rhc2hib2FyZCJ9
  &scope=store.read
  &response_type=code

// Callback
https://app.example.com/oauth/callback
  ?code=...
  &state=eyJjc3JmIjoiYWJjMTIzIiwicmV0dXJuIjoiL2Rhc2hib2FyZCJ9

state is also required as a CSRF countermeasure. Save a random value generated at request time in the session, and verify it matches on callback.

Common errors

Cautions when changing it

When changing the redirect URI of a live app, follow this order.

1. Add the new URI (keep the old URI)
2. Switch the app's code / environment variables to the new URI and deploy
3. Verify behavior with the new URI
4. Delete the old URI

If you delete the old URI abruptly, all authorization requests that occur before the deploy completes will fail.

Related guides

• Creating a new app
• The list of available OAuth scopes
• Back to the developer help index