Tokens and expiry

How long access and refresh tokens last, how to refresh them, and how to store them safely.

A partner API token proves that a shop member approved your app. If it leaks, someone else can read that shop’s data. Follow these rules.

Lifetimes

Refresh tokens rotate: every refresh returns a new one, and the one you used stops working. As long as you refresh regularly, the connection keeps working past 90 days.

Refreshing

const response = await fetch(
  "https://api.toreca-cloud.com/api/auth/oauth2/token",
  {
    method: "POST",
    headers: {
      Authorization: "Basic " + basicCredentials,
      "Content-Type": "application/x-www-form-urlencoded",
    },
    body: new URLSearchParams({
      grant_type: "refresh_token",
      refresh_token: storedRefreshToken,
      resource: "https://api.toreca-cloud.com/partner/v1",
    }),
  },
);
const next = await response.json();
// Save next.refresh_token (the old one no longer works)

• When the API answers 401, refresh and retry once.
• Refresh at most once at a time per connection. Two parallel refreshes make one of them use a stale refresh token and fail.
• Save the new refresh token as soon as you receive it. If saving fails, you can’t refresh again.
• If refreshing fails with invalid_grant, ask a shop member to approve again.

Storing tokens

• Keep tokens and the client secret on your server only. Never put them in a browser, a mobile app or a static site’s JavaScript.
• Encrypt them at rest and limit who and what can read them.
• Keep tokens out of logs, error reports and analytics.
• If the client secret may have leaked, ask the shop admin to regenerate it (“Regenerate secret”). The old secret stops working at once.

When the connection stops

The API refuses calls in these cases even with an unexpired token.

To disconnect from your side, call DELETE /partner/v1/connection. It also revokes every refresh token your app holds for that shop.