What is application registration
This explains what ReceiptRoller's "application registration" is, why it is needed, and what you can do once you register. For the actual registration steps, see The flow to getting started and the later guides in this chapter.
What is application registration
Application registration (hereafter "app registration") is the procedure of registering information as an OAuth client in order to connect an external system to the ReceiptRoller API. By registering, ReceiptRoller can identify "where a request came from" and return only the data within the permitted scope.
Why app registration is needed
The ReceiptRoller API is protected with OAuth 2.0. OAuth 2.0 requires that the client calling the API (the external system) has registered its identity in advance. You cannot suddenly issue an access token without registering.
App registration enables the following.
- Identity proof — uniquely identify the request sender by the client ID / secret
- Declaring the authorization scope — register in advance which scopes this app requests
- Fixing the redirect destination — limit the URL that receives the authorization code, preventing phishing
- Auditing and revocation — revoke access per app if a problem occurs
What is issued when you register
When you register an app, the following credentials and settings are issued / finalized.
| Item | Purpose | Handling |
|---|---|---|
| Client ID | A public ID identifying the app. Sent in the authorization URL / token requests | Fine to make public |
| Client secret | The app's "password". Used on the server side at token exchange | Never make it public. Hold it on the server side only |
| Redirect URI | The URL that receives the authorization code after OAuth authorization (multiple allowed) | The code is only returned to a pre-registered URI |
| Permitted scopes | The set of scopes this app can request | Register the minimum needed |
| UserScopeStatus | The review state when including user.* scopes |
pending / approved / rejected |
The secret is shown only on the screen immediately after creation. If it leaks or is lost, you need to regenerate it, and the existing secret is immediately invalidated. Never embed it in client-side code (a mobile app, an SPA's JS, etc.). Always perform token exchange that uses the secret on the server side.
The app lifecycle
An app is managed through the following flow, from registration to operation to retirement.
- Registration — set the app name, redirect URI, and requested scopes
- Review (only when including
user.*) — moves toapprovedafter the operating team's review - Development — verify behavior with a test redirect URI (
http://localhost, etc.) - Production operation — add the production redirect URI and switch over
- Secret rotation — regenerate the secret periodically or on leak
- Retirement — disable the app when you stop using it (existing tokens are also invalidated)
You can register multiple apps per business account
A single business account can register multiple apps. The following separations are common.
- By environment — make development / staging / production separate apps, and manage redirect URIs and permissions independently
- By purpose — make different use cases separate apps, such as "our e-commerce integration", "BI tool integration", "mobile app"
- By permission — separate a read-only app (
store.orders.read) from a write app (store.orders.write) and operate at least privilege - By client type — register separate apps for a server-side app and one exposed to mobile/SPA
Store-scope apps and User-scope apps
Apps split into two broad types depending on the scopes they request. Because you cannot mix both in one app, register them separately if you handle both.
| Type | Requested scopes | Who consents | Review |
|---|---|---|---|
| Store-scope app | store.* / crm.* / sns.* / analytics.* |
Store owner / administrator | Not needed (usable at registration) |
| User-scope app | user.* |
The individual user themselves | Needed (usable after the operating team's approval) |
For details, see OAuth scopes reference and availability.
An app's disclosure scope
By default, an app registered in the ReceiptRoller developer portal is a private app usable only within the business account that registered it. Providing a public app where "other store owners authorize and use this app" is arranged separately in consultation with the operating team.
- Private app — an app authorized by your own store / your own staff. Internal tools, your own e-commerce integration, etc.
- Public app (consultation required) — an app authorized by other store owners / other users. When providing it as SaaS to other stores, etc.
Prerequisites for app registration
- You have a ReceiptRoller store account
- The business account's plan is Starter or higher (the app registration screen is not shown on the Free plan)
- You have the owner or developer role
If you don't meet the prerequisites, first check The flow to getting started.
The structure of this chapter
This chapter covers the topics around app registration in the following order.
- Creating a new app — the registration screen operations and the input fields
- Setting the redirect URL — settings per development / production environment and common mistakes
- Declaring the purpose of use / connections (POS / e-commerce / analytics, etc.) — entering the metadata at registration
- Applying for review of User-scopes — the additional process when using
user.*
Related guides
-
The flow to getting startedExplains the flow to start using the ReceiptRoller developer portal. If you register as a store user and are on the Starter plan or higher, no separate developer application is needed; you can register an app and begin API implementation right away.
-
Creating a new appExplains the concrete steps to register a new app (OAuth client) in the ReceiptRoller developer portal. Covers the input fields, validation, the post-creation credentials display, and common errors.