Authentication

Your code authenticates with a personal access token that you mint for a store and send as a bearer token.

Authorization: Bearer numu_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

If you are building for one merchant — your own store, an ERP sync, an internal tool — a token is all you need. If you are building something many merchants install, build a partner app: each merchant approves it through OAuth, and your server gets a numu_app_… token for their store.

Mint a token

In the dashboard: Settings → API & webhooks (/settings/developers) → Create key. Or over the API, authenticated as the store owner:

cURL

JavaScript

Python

PHP

The secret is returned once. It is stored hashed, so nobody — including NUMU — can show it to you again. Lost it? Delete the token and mint another.

Scopes

A token carries scopes, and they are the only thing standing between it and everything its owner can do. Nine domains, each with :read and :write:

Scope	Reaches
`catalog`	Products, variants, inventory, categories, bundles, gift cards
`media`	File uploads and stored assets
`orders`	Orders, shipments, returns, refunds, abandoned checkouts
`customers`	Customer records and addresses
`analytics`	Metrics, reports, dashboard figures
`marketing`	Coupons, promotions, campaigns, WhatsApp, inbox
`themes`	Themes, pages, menus, the editor
`risk`	Risk assessments
`settings`	Store settings, locations, shipping, payments, invoices

:write does not imply :read — ask for both if you need both. "*" exists and means every scope; a token that only reads orders should never carry it.

Everything else is denied by default. A token cannot reach admin, staff or platform-billing endpoints, and it can never mint or manage tokens — including its own.

Lifetime and revocation

Tokens expire after 90 days unless you set expires_in_days (up to 3650). Revoke immediately by deleting it:

Revocation is checked on every request, so a deleted token stops working at once.

Check what a token can do

Returns the store it is pinned to and the scopes it carries. Reachable with any valid token, whatever its scopes — useful as a health check in your integration's startup.

Keeping a token safe

Store it as a secret in your deployment, never in source control or a frontend bundle. Anyone holding it acts as the store owner within its scopes.

Mint one token per integration, so revoking one does not break the others.

Ask for the narrowest scopes that work. A shipping integration rarely needs customers:read.

Rotate on a schedule: mint the new token, deploy it, delete the old one.

Mint a token#

Scopes#

Lifetime and revocation#

Check what a token can do#

Keeping a token safe#

Mint a token

Scopes

Lifetime and revocation

Check what a token can do

Keeping a token safe