Creating a new app

app-registration oauth client developer-portal

About this guide
This explains the concrete steps to register a new app in the developer portal. For the concept and big picture of app registration, first read What is application registration.

Creating a new app

Open the developer portal from the ReceiptRoller store dashboard and register a new app (OAuth client). It takes about 3-5 minutes.

Prerequisites

You have a ReceiptRoller store account
The business account's plan is Starter or higher
The logged-in member has the owner or developer role

If you don't meet these, first check The flow to getting started.

Step 1: Open the developer portal

Log in to the store dashboard
Select "Developer" or "Developer portal" from the left menu
The app list screen is displayed

If it does not appear in the menu, check that your plan is not still Free (The flow to getting started).

Step 2: Click "Register app"

Clicking the "Register app" or "Create new app" button in the top-right of the app list screen opens the registration form.

Step 3: Fill in the required items

Item	Required	Description
App name	Required	The name shown to users on the OAuth authorization screen. e.g. "Our e-commerce integration", "Household-budget app XYZ"
Description	Recommended	Describe the app's purpose in 1-2 sentences. Shown on the authorization screen as "This app requests △△ in order to ○○"
Redirect URI	Required	The URL that receives the code after OAuth authorization. Multiple allowed (separate for development / production)
Required scopes	Required	The set of OAuth scopes this app requests. Select the minimum
Purpose of use / connection category	Required	Declare the purpose: POS / e-commerce / analytics / marketing / your own mobile app, etc.
Homepage URL	Optional	The app provider's website. Shown as a "Learn more" link on the authorization screen
Support contact	Optional	An email address for users to contact. Shown on the authorization screen
Privacy policy URL	Required if User-scopes are included	Apps handling individual user data must publish a privacy policy

Tips for the app name

Be specific — "Our e-commerce integration (production)" is easier to manage than "API test"
Include the environment — if you register separate apps for development and production, adding "(dev)" / "(prod)" prevents mistakes
2-30 characters — a length that doesn't break the authorization screen layout

Entering the redirect URI

HTTPS required (production) — http:// is not accepted except for localhost
Exact match — the redirect_uri you specify in the authorization URL must exactly match the URI registered here (including trailing slash and case)
Multiple allowed — e.g. register both http://localhost:3000/callback (development) and https://your-app.example.com/callback (production)
Query / fragment not allowed — ?foo=bar or #hash cannot be included

For details, see the next article, Setting the redirect URL.

Selecting scopes

Select the minimum scopes you need. Adding scopes "just in case" is not recommended. If you add or remove scopes, you will need to re-obtain existing access tokens.

Store-scopes only (store.* / crm.* / sns.* / analytics.*) → usable immediately
Includes User-scopes (user.*) → review required (see the OAuth scopes reference)
Store-scopes and User-scopes cannot be mixed — a single app cannot request both. To handle both, register two apps

Step 4: Click the "Create" button

Once you have filled in all required items, click "Create" or "Register". If there is a validation error, it is shown in red on the relevant field.

Step 5: Store the credentials

After successful creation, the client ID and client secret are displayed.

The client secret is shown only on this screen
Once you close the screen, you cannot display the secret again. Be sure to store it safely with the following steps.

Save it in a password manager (1Password, Bitwarden, etc.)
In production operation, manage it via server environment variables / a secret manager (AWS Secrets Manager, Azure Key Vault, etc.)
Never include it in a Git repository (add the .env file to .gitignore)
If you lose it, you need to regenerate the secret, and the existing secret is immediately invalidated

The client ID is fine to make public. You can check it any time on the app's settings screen.

What you can do after creation

You can reopen the registered app from the app list in the developer portal and do the following.

Edit the app name, description, and URLs — renaming and updating the description can be done any time
Add / delete redirect URIs — manage flexibly as you add environments
Change scopes — existing tokens will need to be re-obtained
Regenerate the secret — on leak, or at periodic rotation. The old secret is immediately invalidated
Disable / delete the app — when you stop using it. Existing access tokens are also invalidated
Check the audit log — the history of major API accesses and token issuances via this app

Common errors

Error	Cause	What to do
"The app registration screen does not appear"	Plan is Free / insufficient role	Upgrade to Starter or higher, and grant the developer role
"The redirect URI format is invalid"	Not HTTPS (except localhost), includes a query/fragment, not an absolute URL	Enter a complete absolute HTTPS URL (e.g. `https://example.com/callback`)
"Store-scopes and User-scopes cannot be specified together"	Mixing `store.` and `user.` in one app	Separate by purpose and register as two apps
"The app name is already in use"	An app with the same name exists in the same business account	Change to a unique name, e.g. by adding an environment name
"Privacy policy URL not entered"	A required item is unfilled while including User-scopes	Enter a published privacy policy URL

Next steps

Once app registration is complete, continue with the following implementation.

Organize redirect URIs — for using development vs. production, see this chapter's Setting the redirect URL
OAuth authorization flow — for implementing the authorization code flow using the client ID and secret, see the API authentication guide
Per-use-case guides — Guide for stores: Webhook / Guide for wallet apps

Related guides

Published: 2026-04-27 Updated: 2026-07-05

Back to help list