If you’re building a product or service that integrates with Stora on behalf of multiple operators, you’re building a partner integration. This guide covers how it works, what we expect, and how to get started.Documentation Index
Fetch the complete documentation index at: https://docs.stora.co/llms.txt
Use this file to discover all available pages before exploring further.
Operator integrations vs partner integrations
There are two ways to connect to the Stora API:| Operator integration | Partner integration | |
|---|---|---|
| Who builds it | The operator (or their developer) | A third-party company |
| Auth flow | Access Token or Client Credentials | Authorization Code (required) |
| Scope | Single operator’s data | Multiple operators, each authorising independently |
| Setup | Self-serve in BackOffice | Managed by Stora |
| Example | Internal reporting dashboard, custom booking widget | Smart entry provider, CRM connector, accounting sync |
How the partner programme works
Get in touch
Contact us with details of what your integration does, which Stora resources
it needs, and the problem it solves for operators.
Development
We’ll set up OAuth 2.0 testing credentials with a set of selected test
operators. You build your integration using the Authorization Code
flow
and our test environment.
Review
Submit your integration for review. We’ll check your use of scopes, External
Events implementation, error handling, and how you present the connection
flow to operators.
Technical requirements
These apply to all partner integrations. Meeting them is part of the review process.Naming and presentation
Your integration must use a distinct product name and must not imply that Stora built, owns, operates, or endorses it. If you’re distributing a plugin, extension, or packaged integration, follow the third-party plugin naming rules before you publish.Authentication
- You must use the OAuth 2.0 Authorization Code flow. No other flow is accepted for partner integrations.
- Handle token refresh correctly — access tokens expire after 2 hours.
- Never ask operators to share or copy-paste credentials. Your integration should handle the OAuth flow end-to-end.
- 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.), follow the broker pattern — PKCE alone is not sufficient for multi-tenant distribution.
Disconnect and reconnect
Your integration must expose operator-facing Disconnect and Reconnect actions in its UI. Operators expect to manage the connection from inside the product they installed — not from Stora BackOffice.- Disconnect must call
POST /oauth2/revokewith a valid token and your OAuth client credentials, then discard the locally stored tokens. Passing either the access token or the refresh token revokes the pair — one call is enough. - Reconnect is re-running the Authorization Code flow. Expose it in the UI even while the current tokens are still valid, so operators can re-grant expanded scopes or switch Stora accounts without uninstalling.
- On uninstall or deprovisioning, your integration must automatically revoke tokens and discard local state. For distributed plugins, wire the same revoke-and-discard into the host’s uninstall hook. For hosted marketplace apps, use the platform’s deprovisioning webhook, such as Shopify’s
app/uninstalledwebhook. These hooks are best-effort; treat them as a hygiene layer on top of the explicit Disconnect action, not a replacement for it.
400 or 401 from the token endpoint), surface a clear “reconnect” prompt to the operator.
For plugin-distributed integrations, see Disconnecting and reconnecting in the broker guide for the broker-side responsibilities.
External Events
When your integration takes an action in Stora on behalf of an operator, it must be visible to them. You’re required to create Timeline Events for actions originating on your platform. For example:- “Unit locked via YourApp”
- “Customer contacted via YourApp”
Rate limits
Standard rate limits apply (10 requests/second, 60 requests/minute) per operator, shared with their other API usage. Strategic partners may negotiate independent higher limits for operators using their integration. Your integration must implement backoff when receiving429 responses — see rate limiting.
Idempotency
UseIdempotency-Key headers on all POST requests to prevent duplicate operations. See idempotent requests.
Error handling
Handle all documented error codes gracefully. Do not retry indefinitely on4xx errors.
Metadata
Use themetadata field to store your own references on supported resources (contacts, orders, tasks, notes, webhook endpoints) rather than maintaining external mapping tables.