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
An expiring token you generate in the Developer Portal and use directly in API requests. Use Access Tokens for one-time scripts, API exploration, or short-lived AI-agent tasks. Choose a short expiry and only the scopes your task needs.
OAuth 2.0 applications
OAuth issues short-lived access tokens that expire after 2 hours. Choose the flow that matches your integration:
- Client Credentials — for ongoing server-to-server access to an account you manage. Use OAuth clients under Connected accounts in the Developer Portal and repeat the token exchange before expiry.
- Authorization Code — for partner apps that operators authorise themselves. Your app handles the browser approval flow and uses refresh tokens to maintain access.
For a managed-account integration, start with Connect an account, then follow API credentials. For a partner app, follow Building a partner integration and the Authorization Code walkthrough below.
Option A: Access token
Follow Use an Access Token to create an expiring token for your test operator or connected account. Use it directly in the bearer header of your first API request.
Option B: OAuth 2.0 — Client Credentials
Use this when your backend needs ongoing access to an account you manage, without user interaction. Follow Use an OAuth Client for client creation, token exchange, authenticated requests, and renewal.
Client Credentials does not issue a refresh token. Your backend obtains a replacement access token by repeating the client_credentials exchange.
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:
The user logs in to Stora and approves the requested scopes. Stora redirects back to your redirect_uri with an authorisation code:
Step 2: Exchange the code for tokens
Response:
Refreshing tokens
Access tokens expire after 2 hours. Use the refresh token to get a new one without requiring the user to re-authorise:
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. code_verifier and code_challenge before redirecting:
Add the challenge to the authorisation URL:
Include the code_verifier when exchanging the code:
