# Partners

> How a platform that runs many businesses runs all of Nexafon inside itself, with stores, partner keys, staff sign-in and partner-wide webhooks.

Source: https://docs.nexafone.so/v1/partners/

A **partner** is a platform such as a marketplace or a restaurant system. Each business on it is a Nexafon **store**,
an ordinary workspace with its own WhatsApp number, inbox, calls, billing and commerce, linked to the partner by the
partner’s own id for it (`externalRef`). Store owners and staff never open Nexafon: everything runs inside the
partner’s platform.

| Step | How | Guide |
| --- | --- | --- |
| Nexafon sets up the partner | Domains, default store plan and default appearance, and the partner’s keys | Below |
| The partner’s server creates stores | `POST /api/v1/partner/stores` with a partner secret key | [Partner API](/v1/partners/api/) |
| It keeps products in sync | Products and categories per store | [Catalog sync](/v1/commerce/catalog/) |
| Staff open Nexafon inside the platform | A partner user token listing their stores, and `<nexafon-app>` | [User tokens and the full app](/v1/partners/user-tokens/) |
| Users with several stores switch between them | The store switcher inside the embed | [Store switcher](/v1/partners/store-switcher/) |
| The platform hears every store’s events | One partner-wide webhook endpoint | [Partner webhooks](/v1/partners/webhooks/) |

## What Nexafon sets up for you

Nexafon creates the partner in its console with:

- the partner’s **domains**: every store’s embed may be framed on them, and partner sessions start only there;
- the **default store plan**: every new store starts on it, with its included seats and features (such as
  `commerce.orders`);
- the **default appearance** of all its stores’ embeds;
- the partner’s **keys**: secret keys `psk_live_…`/`psk_test_…` (with scopes and an optional IP allow-list) for the
  partner’s servers, and publishable keys `ppk_live_…`/`ppk_test_…` for its pages. Each is shown once.

A suspended partner’s keys, sessions and store embeds stop working until Nexafon reactivates it; the stores’ data
is kept.

## Partner key scopes

A partner secret key carries partner permissions for the Partner API:

| Permission | Lets the key | Needs plan feature |
| --- | --- | --- |
| `partner.account:view` | See the partner's profile, status and default store plan |  |
| `partner.stores:manage` | Create, rename, close and reopen the partner's stores |  |
| `partner.stores:view` | See the partner's stores |  |
| `partner.webhooks:manage` | Manage the partner-wide webhook endpoints that receive every store's events |  |

…and any [workspace permissions](/v1/security/#secret-key-scopes) it acts with inside the partner’s stores. A key
that signs [partner user tokens](/v1/partners/user-tokens/) needs `partner.stores:manage`, and the sessions it starts
act with no more than its workspace permissions.

## The example

`examples/partner` (a Node server and a React page) creates two stores, signs a partner user token for both, embeds
`<NexafonApp/>` and verifies an order webhook; it runs in CI with Playwright.