Authentication

Prerequisites

You’ll need a Developer Portal account. Use the Developer Portal to create a test operator, manage API access for a connected operator account, or create a partner app. You do not need to connect a real operator account just to explore the API.

Create a test operator first if you’re exploring the API. Test operators let you try credentials, requests, and webhook setup before working with real operator data.

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 in the Developer Portal. Use it immediately in requests — no token exchange needed. Good for: scripts, internal tools, quick automations, exploring the API.


Setup	Generate in the Developer Portal
Security	The token is long-lived. Store it securely.
Expiry	Configurable when you create it
Scopes	Configurable, 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.


Setup	Create or manage credentials in the Developer Portal
Security	Tokens are short-lived (2 hours)
Expiry	Automatic — request or refresh tokens as needed
Scopes	Configurable, 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

Open the Developer Portal

Go to developer.stora.co and choose the flow that matches your work: Testing / looking around, Manage accounts, or Create partner app.

Generate a token

Create an access token for your test operator or connected operator account.

Choose your scopes

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

Set an expiry date

Choose when the token should expire.

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.

Open the Developer Portal

Go to developer.stora.co and choose Testing / looking around for test credentials, Manage accounts for a connected operator account, or Create partner app for a multi-operator integration.

Create or select an operator context

Use a test operator for exploration. Use Manage accounts when you need credentials for a specific real operator.

Create Client Credentials

Create OAuth 2.0 Client Credentials and select the scopes your application needs.

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 Stora 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) protects the Authorization Code flow against code interception. Use it when your OAuth client is a single-user application running on a user-owned device — a mobile app, a desktop app, or a CLI tool.

If you’re distributing your integration as code that runs outside infrastructure you control (WordPress plugin, browser extension, client-side app extension, packaged on-premise tool, etc.), PKCE alone is not sufficient. Follow Distributing a public plugin instead — the broker pattern it describes is the safe way to keep OAuth credentials and tokens out of distributed code.

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

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"

​Prerequisites

​Choose your connection method

​Access tokens

​OAuth 2.0 applications

​Option A: Access token

​Option B: OAuth 2.0 — Client Credentials

​Option C: OAuth 2.0 — Authorization Code

​Step 1: Redirect the user to authorise

​Step 2: Exchange the code for tokens

​Refreshing tokens

​PKCE (optional)

Prerequisites

Choose your connection method

Access tokens

OAuth 2.0 applications

Option A: Access token

Option B: OAuth 2.0 — Client Credentials

Option C: OAuth 2.0 — Authorization Code

Step 1: Redirect the user to authorise

Step 2: Exchange the code for tokens

Refreshing tokens

PKCE (optional)