A Polar token that can only read
Polar names its scopes exactly, which makes this the most precise key here to create.
The four scopes, and what each one powers
Open the organization settings in Polar, go to Developers, and create an Organization Access Token. The scope list is long; four of them matter, and they are named on screen exactly as they are written here — these are Polar's own scope strings, taken from the list its OAuth metadata publishes, not a paraphrase.
orders:read powers every revenue figure on the site — the headline total, the trend, refunds, revenue by product and by country, and the orders table itself. subscriptions:read powers monthly recurring revenue, the active and cancelling counts, the subscription mix and the subscriptions table. customers:read powers the buyer name and email on an order at a provider that does not put them on the order itself, and the mirrored customer records. products:read powers the products table — what you sell, with what it has earned beside it wherever the provider attaches a product to an order.
- orders:read
- Every revenue figure and the orders table
- subscriptions:read
- Recurring revenue and the subscriptions table
- customers:read
- Buyer details an order does not carry
- products:read
- The products table
Give it an expiry, and set a reminder
Polar lets you put an expiry on an access token, and a token that expires is a better token than one that does not. The tradeoff is that an expired token fails silently in the sense that matters: the sync records an error against the account, and the figures stop moving until you notice.
So if you set one, set a reminder for a week before it. Replacing a token is not a swap here — see below — so it is worth not being surprised by.
Scopes can change after you connect
The four resources are re-probed on every refresh rather than only at connect, because a token's scopes can be edited in Polar months after it was pasted in here. The scopes recorded at connect are the baseline each later sync is compared against.
Drift is reported in both directions and neither is treated as a sync failure. Losing a scope means the figures it powered quietly stopped updating. Gaining one means somebody edited that token, which is worth knowing even though it is not, on its own, evidence of anything.
Replacing or revoking the token
There is no replace-the-token screen today, and this page is not going to imply one. Changing the credential means disconnecting the account here and connecting it again with the new one. Disconnecting deletes the mirrored copy of that account's rows, which is why it is confirmed in place with a sentence naming exactly what goes; the first sync after reconnecting rebuilds it from Polar. Nothing is lost permanently, but it is a rebuild rather than a swap, so do it when you can wait for a sync.
Revoking the token at Polar without reconnecting is the gentler case: the account and its last-synced figures stay exactly where they are, and the failure is recorded against it rather than silently swallowed.
While it is stored, the token is encrypted with AES-256-GCM under a per-value random initialisation vector before it reaches the database, and decrypted only inside the sync. Nothing derived from it beyond a short hint is ever sent to the browser.
