Skip to main content

Authentication and OAuth 2.0

SitePack uses OAuth 2.0 to authorize apps to access merchant data. Merchants stay in control of which apps can access their site and what those apps may do.

You only need this page for an API integration. A storefront app that only renders blocks and uses App Settings needs no OAuth at all.

API Host​

Every API and OAuth request goes to https://api.sitepack.eu, for example https://api.sitepack.eu/api/public/v1/products.

Authentication Methods​

Depending on your app's architecture, SitePack supports two primary authentication methods:

1. OAuth 2.0 (Authorization Code Grant)​

Used for Remote Apps (e.g., iframed apps or background services) that need to act on behalf of a merchant. This flow provides your app with an access_token and a refresh_token.

Flow Overview:

  1. Authorization: You send the merchant to SitePack's authorization endpoint with the scopes you need. They can arrive from your own install link, or by clicking "Install" on your listing in the SitePack Marketplace.
  2. Consent: The merchant signs in, chooses which of their sites to install the app on, reviews the requested permissions (and accepts the recurring charge if your app has a paid plan), and approves. SitePack redirects them back to your redirect_uri with an authorization_code.
  3. Token Exchange: Your app exchanges the authorization_code for an access_token (and a refresh_token) at the SitePack token endpoint.
  4. Authorized Requests: Your app uses the access token in the X-SitePack-Access-Token header for all API requests.

2. Device Code Grant​

Used for CLI tools and devices without a browser. Your app requests a device code, shows the merchant a short verification URL to approve in their browser, and then polls the same token endpoint with grant_type=urn:ietf:params:oauth:grant-type:device_code. This is how the SitePack CLI authenticates.

The OAuth Flow in Detail​

GET https://api.sitepack.eu/api/authentication/oauth/authorize

Query parameters:

ParameterDescription
client_idYour app's Client ID, from the OAuth & install card in the Partner Portal.
response_typecode.
scopeA space-separated list of the scopes you need.
redirect_uriWhere SitePack sends the merchant back. Must match the redirect URI registered for your app.
stateAn opaque value you generate; SitePack returns it unchanged so you can guard against CSRF.
site_idOptional. Pre-select (and lock) a specific site by its uuid. Omit it to let the merchant pick from the sites they manage.

The consent screen shows your app, the site it will be installed on (the merchant's current site, or the one named in site_id), and the requested permissions grouped by area in plain language. Scopes that can spend the merchant's money (domains:order, mail:order) are called out separately. Only scopes your app declared in its app.json can be granted, even if the link asks for more.

On approval SitePack installs the app on the chosen site and redirects back with the code, a signature so you can verify the redirect came from SitePack, and a link back into SitePack:

https://your-app.com/auth/callback?code={authorization_code}&state={state}&signed_at={unix_time}&signature=v1={hmac}&manage_url={sitepack_admin_url}

signature is an HMAC-SHA384 over "{signed_at}.{code}.{state}", keyed on your Webhook signing secret (the same key as webhooks). Recompute it and compare in constant time before trusting the callback; state still guards against CSRF, this adds origin and integrity. Verifying is optional but recommended: the authorization code is single-use and only exchangeable with your client_secret.

manage_url is the page in the merchant's SitePack admin where your app is managed. When your own onboarding finishes, redirect the merchant to manage_url so they land back in SitePack.

If the merchant denies access, SitePack redirects back with ?error=access_denied&state={state} instead.

Step 2: Exchange the code for a token​

Your server makes a POST request to the token endpoint. The body is application/x-www-form-urlencoded:

POST https://api.sitepack.eu/api/authentication/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&code={authorization_code}

Step 3: Receive the access token​

SitePack responds with the tokens:

{
  "access_token": "at_12345...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "content:read media:write",
  "refresh_token": "rt_67890..."
}

The scope is the intersection of what you requested and what the merchant granted, so read it back rather than assuming you received everything you asked for.

Managing Tokens​

  • Access Tokens: These are short-lived (expires_in seconds). Refresh them before they expire.
  • Refreshing: POST to the same token endpoint with grant_type=refresh_token, your client_id, client_secret and the refresh_token. You receive a new access token and refresh token.
  • Security: Never store client_secret or refresh_token in client-side code (JS). Always handle these on your secure backend.
  • Revocation: Merchants can revoke your app's access at any time from their SitePack Admin. Your app should gracefully handle 401 Unauthorized errors.

Using the Access Token​

Send the token in the X-SitePack-Access-Token header on every request to the versioned public API at https://api.sitepack.eu/api/public/v1:

GET https://api.sitepack.eu/api/public/v1/products
X-SitePack-Access-Token: YOUR_ACCESS_TOKEN
tip

X-SitePack-Access-Token: <token> is the preferred header. A standard Authorization: Bearer <token> header is also accepted, so existing OAuth libraries keep working, but new apps should send X-SitePack-Access-Token.

Next Steps​