Installs and tokens
How a shop installs your app, how you get its tokens, and how they rotate.
Installs start in Storeware
A merchant installs from Storeware's own consent screen, which lists every scope, event, host and panel your release asks for. Link to it from your site:
https://app.storeware.ai/install/<your slug>Your app learns of the install in one of two ways, and the SDK handles both:
- An app with a home: the first time the merchant opens it, the admin hands it a session token. Trade it with your client secret for the shop's tokens (RFC 8693 token exchange).
- Any app:
app.installed.v1is posted to your webhook URL carrying a one time install grant. Trade it with your client secret within the hour.
Either way you receive an access token, a refresh token, and the shop's webhook and session secrets. The secrets are handed over once. Keep them somewhere durable.
Tokens
- An access token lasts 24 hours. Send it as
Authorization: Bearer. - A refresh token rotates: using it ends it and returns a new pair. Save the new pair before using it. Presenting a spent refresh token is treated as theft and ends the installation's tokens.
- Each installation may make 240 calls a minute. Past that the API answers 429 with
Retry-After.
Client secrets
An app may hold two live production secrets at once, so you can rotate without downtime: make the new one, deploy it, then end the old one with a grace period. Development secrets work only on development stores; app dev makes one for you. Making a production secret needs a sign in to the admin within the last half hour.