> ## 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**         | Manage a connected operator account in the Developer Portal | Create and submit a partner app in the Developer Portal |
| **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="Create a partner app">
    Use the [Developer Portal](/2025-09/guides/developer-portal) to create a partner application for your integration.
  </Step>

  <Step title="Develop and test">
    Use test operators in the Developer Portal while you build your integration with the [Authorization Code flow](/2025-09/guides/authentication#option-c-oauth-2-0-%E2%80%94-authorization-code). Test applications can be used with your test operators, or with real operators that accept an application invitation.
  </Step>

  <Step title="Prepare your listing">
    Manage your partner application listing for [`marketplace.stora.co`](https://marketplace.stora.co) in the Developer Portal.
  </Step>

  <Step title="Submit for review">
    Submit your application approval request when your integration is ready. Before you submit, use the [partner approval checklist](/2025-09/guides/partner-approval-checklist) to review scopes, External Events, error handling, connection lifecycle, and operator-facing behavior.
  </Step>

  <Step title="Go live">
    Once approved, your integration becomes available to operators through the marketplace.
  </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.

### Identify the connected operator

Use [`GET /oauth2/token/info`](/2025-09/api-reference/oauth-2/retrieve-info-for-the-access-token) 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.

<Tip>
  You can use this endpoint as the initial request to verify the connection.
</Tip>

### 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`](/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 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](/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, 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](/2025-09/guides/developer-portal), develop with test operators, review the [partner approval checklist](/2025-09/guides/partner-approval-checklist), then submit your application for review.