Creating a new app

app-registration oauth client developer-portal

To use the ReceiptRoller API, you first register a developer app (an OAuth client) in a business account and receive a client ID and client secret. This article covers how to open the registration screen, the fields, how the credentials are shown after creation, what you can do afterwards, and common stumbling points. For the idea behind app registration, see What is application registration.

Before you start

The business account that will own the app must be on the Starter plan or above.
Only the business account's owner can create, edit, regenerate the secret of, or delete an app. Other members can only view the app list and app details.

Open the developer apps screen

In the business account's details, open the menu (⋮) and choose "Developer apps".
Or open /en/developers/get-started and choose a business account.

The screen's URL is /en/organizations/{business account ID}/developer/apps. If the plan is below Starter, you are taken to a page that offers a plan change.

Create the app

Press "Create App", fill in the fields below and create it.

Field	Required	Description
App Name	Yes	Up to 200 characters. If you keep separate apps for development and production, adding "(dev)" or "(prod)" helps avoid mix-ups.
Description	No	Up to 1,000 characters.
Redirect URI	Needed for OAuth	The one URL that receives the code after authorization. Without it, the authorize URL returns `invalid_redirect_uri`.
Website URL	No	The app provider's website.
Bind the access token to one business account at authorize time	On by default	Leave it on for most apps. When on, the user picks one business account on the consent screen and the token works only for that business account. Turn it off for mobile apps that switch between business accounts inside the app; they pass `organizationId` on each API call.
Public client (mobile app)	Off by default	Turn on for native apps such as Android and iOS. When on, the app uses no client secret and PKCE is required. Leave it off for apps that run on a server.
API Scopes	Choose them	Tick the scopes your app uses. Only the scopes chosen here can be granted at authorization.

About the redirect URI

The redirect_uri in the authorize URL must match the registered value exactly, including letter case, trailing slash and port.
An app has one redirect URI. If development and production use different URIs, create a separate app for each environment.
Do not include a query string. After authorization, ?code=… is appended to the registered URI.

For details, see Setting the redirect URL.

Choosing scopes

Choose only the scopes your app actually uses.
Including user.* scopes puts the app into review. Until it is approved, an app with binding on that requests user.* gets app_not_approved (Applying for review of User-scopes).
An app with binding on cannot mix user.* and other scopes in one authorize request (invalid_scope). If you need both, split the requests or the apps.
Sending a scope that does not exist shows "These scopes do not exist" and the app is not created.

The scope list is in the API Authentication Guide and OAuth Scopes Reference and Availability.

Note down the credentials

After creation you land on the app's details page, where "Credentials" shows two values.

Client ID: a string starting with app_. You can view and copy it on the details page at any time.
Client secret: shown once, on the details page right after creation. It cannot be shown again after you leave, so copy it now and keep it in your server's environment variables or a secret manager. If you lose it, regenerate it.

An app created as a public client shows no secret. Do not put a secret in the app; authorize with PKCE. For storage advice, see Managing the client ID and client secret.

What you can do afterwards

Open the app from the developer apps list to do the following (owner only).

Edit: change the app name, description, redirect URI, website URL, the binding setting, the public client setting and the scopes. A changed redirect URI applies from the next authorize request.
Change scopes: tokens already issued keep their scopes. To use new scopes, have the user authorize again.
Regenerate the secret: the old secret stops working at once and the new one is shown once. If you turn a public client back into a confidential one, regenerate the secret and set it in your app.
Register webhooks: from the webhook section of the details page (Receive new sales by webhook and post them to Slack).
Delete: cannot be undone. The app's tokens and connections are deleted with it.

For apps without user.* scopes, the details page also shows the steps to make a first API call with that app.

Common stumbling points

Symptom	Cause	What to do
Opening developer apps shows a plan change page	The business account's plan is below Starter	Move to Starter or above.
There is no "Create App" button	You are not the business account's owner	Ask the owner to create the app.
"These scopes do not exist"	A scope name that does not exist was sent	Choose scopes from the list again.
`invalid_redirect_uri` on the authorize URL	No redirect URI registered, or it does not match	Register the URI on the edit page and make the authorize URL match it exactly.
You did not copy the secret	It is shown only once	Regenerate it on the details page.

Next steps

Published: 2026-04-27 Updated: 2026-10-26