Building a partner integration

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.

​

Operator integrations vs partner integrations

There are two ways to connect to the Stora API:

​

How the partner programme works

After launch, we monitor usage and operator feedback. Any changes to your integration’s scopes go through a lightweight review process.

​

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.

​

Identify the connected operator

Use GET /oauth2/token/info with the current access token to inspect the connected account and granted scopes. Your integration must display the returned operator.name in your app. A single Stora staff member can have access to multiple operators, so they need to know which operator account is connected. Use the returned scopes to check whether the current token includes the permissions your integration needs. If a newly added feature requires scopes that are missing, prompt the operator to reconnect through the Authorization Code flow so they can re-authorise the expanded scopes.

​

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.

• Disconnect must call POST /oauth2/revoke with 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/uninstalled webhook. These hooks are best-effort; treat them as a hygiene layer on top of the explicit Disconnect action, not a replacement for it.

Operators may also terminate connections outside your integration. When your integration detects a refresh failure (a 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”

Use Timeline Sources and Templates to structure these events. If you need custom Templates specific to your integration, we’ll review and create them during the onboarding process.

​

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 receiving 429 responses — see rate limiting.

​

Idempotency

Use Idempotency-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 on 4xx errors.

​

Metadata

Use the metadata field to store your own references on supported resources (contacts, orders, tasks, notes, webhook endpoints) rather than maintaining external mapping tables.

​

Webhooks

Use webhooks to react to Stora events rather than polling. This is more efficient, gives you real-time data, and respects rate limits.

​

Scope principles

We follow the principle of least privilege. Your production credentials will be scoped to only the permissions your integration needs — nothing more. During development, use test operators in the Developer Portal so you can explore freely. Test applications can only be used with your test operators or operators that accept an application invitation. At review time, we’ll agree on the minimum set of scopes for production. If you need additional scopes after launch (e.g. you’re adding a new feature), submit a request with justification. Operators who have already connected will need to re-authorise to grant the new scopes.

​

Get started

Ready to build a partner integration? Create a partner app in the Developer Portal, develop with test operators, review the partner approval checklist, then submit your application for review.