A scope is a permission a merchant grants your app when they connect it. You choose scopes when you submit the app. Each scope is reviewed. On the consent screen, merchants read a plain-language description of every scope before they approve.
These are the only scopes an OAuth app can request. Other Data-In writes, such as orders, belong on an API key for your own shop, not on an OAuth app.
Available Scopes
The description is the wording merchants see, with your app's name in place of Your app.
| Scope | Type | What merchants read on the consent screen |
|---|---|---|
ads-metrics:read | Read | Send metrics data to Your app from your Triple Whale account |
ads-metrics:write | Write | Access metrics data in Your app and display it in Triple Whale |
attribution:read | Read | Send attribution data to Your app from your Triple Whale account |
moby:read | Read | Fetch any data from your Triple Whale account using Triple Whale MCP |
ads:write | Write | Write ads data from Your app to your Triple Whale account ads table |
email-sms:write | Write | Write email/SMS marketing data from Your app to your Triple Whale account |
offline_access is added to every authorization request so your app receives a refresh token. It appears as a grey badge next to your granted scopes. You do not select it.
Read vs Write Scopes
- Read scopes let your app pull the merchant's data out of Triple Whale.
- Write scopes (those ending in
:write) let your app push data into the merchant's Triple Whale account. The form asks for a Write scope justification: What data will you push to Triple Whale, and where does it come from? Write scopes get a closer look during review. - When a write scope is approved, Triple Whale also registers your app as a data provider under your provider id. Pushed data is attributed to that id.
moby:readand MCP
moby:readis the scope for apps that use the Triple Whale MCP server. A merchant can connect that app only to shops whose plan includes MCP. See Merchant Consent and Disconnecting an App.
Changing Scopes Later
You can change scopes after approval. Every scope change is a change request. It is reviewed before it goes live, and the app keeps its current scopes until then. See Editing an Approved App.
Best Practices
- Request the smallest set of scopes you need. Extra scopes make the consent screen longer and the review slower.
- If you only need to read data, do not request a write scope in case you need it later. Add it with a change request when you are ready to push data.