Skip to main content

​
Prerequisites

You’ll need:
  • A Stora account with an active operator
  • A staff member with permission to manage API settings
  • Access to BackOffice → Settings → Public API
Stora doesn’t currently offer self-service sandbox access. Contact us directly if you need a test environment.

​
Choose your connection method

Stora supports two ways to authenticate. Both use the same scopes and the same Authorization: Bearer <token> header — they differ in how you get the token.

​
Access tokens

A static secret key you generate directly in BackOffice. Use it immediately in requests — no token exchange needed. Good for: scripts, internal tools, quick automations, exploring the API.
SetupInstant — generate in BackOffice
SecurityThe token is long-lived. Store it securely.
ExpiryConfigurable when you create it
ScopesConfigurable, can be modified later

​
OAuth 2.0 applications

Short-lived access tokens issued via the OAuth 2.0 standard. Supports two grant types:
  • Client Credentials — server-to-server, no user interaction required
  • Authorization Code — for partner integrations where an operator authorises your app
Good for: production integrations, third-party apps, anything you share with others.
SetupCreate an application in BackOffice
SecurityTokens are short-lived (2 hours)
ExpiryAutomatic — request or refresh tokens as needed
ScopesConfigurable, can be modified later
Start with an access token to explore the API. Move to an OAuth application when you’re building for production or distributing to third parties.

​
Option A: Access token

1

Generate a token

Go to BackOffice → Settings → Public API and click Generate Access Token.
2

Choose your scopes

Start with read-only scopes (e.g. public.site:read).
3

Set an expiry date

Choose when the token should expire.
4

Copy the token

Copy it immediately — you won’t be able to see it again.
Use it directly in requests: 
curl -X GET "https://public-api.stora.co/2025-09/sites" \
  -H "accept: application/json" \
  -H "authorization: Bearer YOUR_ACCESS_TOKEN"

​
Option B: OAuth 2.0 — Client Credentials

Use this when your server needs to talk to Stora without user interaction.
1

Create an application

Go to BackOffice → Settings → Public API and click Create Application.
2

Choose your scopes

Select the scopes your application needs.
3

Note your credentials

Copy your client_id and client_secret.
Exchange your credentials for a short-lived access token: 
curl -X POST "https://public-api.stora.co/oauth2/token" \
  -H "content-type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "scope": "public.site:read"
  }'
Response: 
{
  "access_token": "ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "public.site:read",
  "created_at": 1710000000
}
Use the access_token in subsequent requests. It expires after 2 hours (expires_in: 7200) — request a new one before it does.

​
Option C: OAuth 2.0 — Authorization Code

Use this when building a partner integration where an operator’s staff member authorises your app to access their data.

​
Step 1: Redirect the user to authorise

Direct the user’s browser to: 
https://app.stora.co/oauth2/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=public.contact:read public.order:read
The user logs in to the Stora BackOffice and approves the requested scopes. Stora redirects back to your redirect_uri with an authorisation code: 
https://yourapp.com/callback?code=AUTHORIZATION_CODE

​
Step 2: Exchange the code for tokens

curl -X POST "https://public-api.stora.co/oauth2/token" \
  -H "content-type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://yourapp.com/callback"
Response: 
{
  "access_token": "ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "public.contact:read public.order:read",
  "created_at": 1710000000,
  "refresh_token": "REFRESH_TOKEN"
}

​
Refreshing tokens

Access tokens expire after 2 hours. Use the refresh token to get a new one without requiring the user to re-authorise: 
curl -X POST "https://public-api.stora.co/oauth2/token" \
  -H "content-type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "refresh_token=REFRESH_TOKEN"
The response includes a new access_token and a new refresh_token. The previous refresh token is revoked.

​
PKCE (optional)

PKCE (Proof Key for Code Exchange) adds an extra layer of security to the Authorization Code flow. It’s optional but recommended for:
  • Distributed plugins (e.g. WordPress, Shopify) where the client secret is in distributed source code
  • Mobile or desktop applications where secrets can’t be stored securely
  • Single-page applications where source code is visible in the browser
To use PKCE, generate a code_verifier and code_challenge before redirecting: 
CODE_VERIFIER=$(openssl rand -base64 64 | tr -d '=/+\n' | head -c 128)
CODE_CHALLENGE=$(echo -n "$CODE_VERIFIER" | openssl dgst -sha256 -binary | base64 | tr -d '=' | tr '/+' '_-')
Add the challenge to the authorisation URL: 
https://app.stora.co/oauth2/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=public.contact:read public.order:read&
  code_challenge=CODE_CHALLENGE&
  code_challenge_method=S256
Then include the code_verifier when exchanging the code: 
curl -X POST "https://public-api.stora.co/oauth2/token" \
  -H "content-type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "code_verifier=CODE_VERIFIER"