Recipe — Token issue & refresh

Goal: obtain and renew Partner API access tokens server-side.

Prerequisites

• Approved app with client_id and client_secret
• Server environment (never expose secret to the browser)

Initial token (client_credentials)

POST /partner/v1/oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "scope": "shop:read board:read"
}

Alternative: application/x-www-form-urlencoded with the same fields, or HTTP Basic client_id:client_secret.

Response (TokenResponse):

• access_token — use on API calls
• expires_in — seconds until expiry
• refresh_token — store securely for renewal
• scope — granted scopes

Refresh before expiry

On success the previous refresh_token is deleted from D1 (not soft-revoked). Expired tokens are purged on token/health calls — do not expect old hashes to remain.

POST /partner/v1/oauth/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "STORED_REFRESH_TOKEN",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

Notes

• No OAuth authorize / redirect — machine-to-machine only.
• On 401 from API, refresh once; if still failing, re-issue with client_credentials.
• See examples/curl-token.md.