> ## 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.

# Building a partner integration

> Build integrations that work across multiple Stora operators and partner with us.

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:

|                   | 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 |

<Warning>
  Operators must never share their access tokens or Client Credentials with
  third parties. If you're a third party building an integration, you must use
  the Authorization Code flow.
</Warning>

## How the partner programme works

<Steps>
  <Step title="Get in touch">
    Contact us with details of what your integration does, which Stora resources
    it needs, and the problem it solves for operators.
  </Step>

  <Step title="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](/2025-09/guides/authentication#option-c-oauth-2-0-%E2%80%94-authorization-code)
    and our test environment.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Go live">
    Once approved, we'll create production credentials scoped to the minimum
    permissions your integration needs. Your integration becomes available to
    all operators.
  </Step>
</Steps>

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](/2025-09/guides/third-party-plugin-naming) before you publish.

### Authentication

* You **must** use the [OAuth 2.0 Authorization Code flow](/2025-09/guides/authentication#option-c-oauth-2-0-%E2%80%94-authorization-code). No other flow is accepted for partner integrations.
* Handle [token refresh](/2025-09/guides/authentication#refreshing-tokens) 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](/2025-09/guides/distributing-public-plugins) — 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/revoke`](/2025-09/api-reference/oauth-2/revoke-an-access-token) 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](/2025-09/guides/authentication#option-c-oauth-2-0-%E2%80%94-authorization-code). 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 revoke the grant in Stora BackOffice. 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](/2025-09/guides/distributing-public-plugins#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](/2025-09/api-reference/timeline-events/create-an-event)** 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](/2025-09/guides/requests#rate-limiting).

### Idempotency

Use `Idempotency-Key` headers on all `POST` requests to prevent duplicate operations. See [idempotent requests](/2025-09/guides/requests#idempotent-requests).

### Error handling

Handle all [documented error codes](/2025-09/guides/errors) gracefully. Do not retry indefinitely on `4xx` errors.

### Metadata

Use the [`metadata` field](/2025-09/guides/metadata) to store your own references on supported resources (contacts, orders, tasks, notes, webhook endpoints) rather than maintaining external mapping tables.

### Webhooks

Use [webhooks](/2025-09/guides/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, your test credentials will have all scopes so you can explore freely. 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? Please complete our [partnership integration application form](https://storestuff.typeform.com/to/CtjBfvK8). Your application will be reviewed within 10 business days, and we'll be in touch to discuss next steps.