> ## Documentation Index
> Fetch the complete documentation index at: https://swapnice.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Partner SDK

> Install the Swapnice Partner SDK and start a consented integration.

The Partner SDK is the supported way to integrate Swapnice. It wraps the Partner API so your app can connect a customer you already know, collect purpose-limited consent, send activity events, and read permissioned profile intelligence.

Partners do not call the consumer Firebase backend. Use this SDK (or the [HTTP API](/partners/api-overview) underneath it). Consumer product guides live under [Swapnice App](/introduction).

<Card title="Integration guide and sample code" icon="terminal" href="/partners/integration" horizontal>
  Implementation requirements, OAuth, consent, events, profile reads, and TypeScript, Python, and cURL examples.
</Card>

```bash theme={null}
npm install swapnice-sdk-ts
```

## What this documentation covers

These guides are written for technical teams preparing an integration review or pilot.

<CardGroup cols={2}>
  <Card title="SDK and API integration" icon="code" href="/partners/integration">
    Implementation requirements, OAuth, consent, events, and sample code.
  </Card>

  <Card title="SDK versus API" icon="scale-balanced" href="/partners/sdk-vs-api">
    Where the SDK adds capability beyond raw HTTP, and when to call the API directly.
  </Card>

  <Card title="Data collection" icon="database" href="/partners/data-collection">
    What the SDK observes, how it is collected, when it is sent, and what never leaves the device.
  </Card>

  <Card title="Outputs" icon="chart-line" href="/partners/outputs">
    Profiles, claims, and intent scores partners can read today.
  </Card>

  <Card title="Architecture and data flow" icon="diagram-project" href="/partners/architecture">
    End-to-end path from a consumer action to a Swapnice output.
  </Card>

  <Card title="Sandbox and testing" icon="flask" href="/partners/sandbox">
    Environments, credentials, and the expected implementation and test process.
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/partners/authentication">
    OAuth 2.1, PKCE, scopes, tokens, and the errors that usually block a first call.
  </Card>

  <Card title="Consent and linking" icon="link" href="/partners/consent">
    Partner customer vs Swapnice account, purposes in product language, revocation.
  </Card>

  <Card title="Events and intents" icon="bolt" href="/partners/events-and-intents">
    Event catalog, intent ontology, claims vs overwrites, and confidence guidance.
  </Card>

  <Card title="Catalog entries" icon="layer-group" href="/partners/catalog">
    How SKUs and collectibles become objects intents can attach to.
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Example use cases" icon="lightbulb" href="/partners/use-cases">
    Worked partner scenarios for personalization, checkout, and catalog flows.
  </Card>

  <Card title="Request walkthrough" icon="list-ol" href="/partners/request-walkthrough">
    Ordered sandbox calls from authorize through profile read and revoke.
  </Card>

  <Card title="What a pilot enables" icon="flag-checkered" href="/partners/pilot">
    What integrating the SDK unlocks in the partner product.
  </Card>

  <Card title="API reference" icon="square-terminal" href="/partners/api-overview">
    OpenAPI playground for every Partner API route.
  </Card>
</CardGroup>

## How the product is structured

<Steps>
  <Step title="Connect and consent">
    The partner creates a customer record, starts a connection session, and records a consent receipt for specific purposes such as `personalization` or `analytics`.
  </Step>

  <Step title="Ingest events">
    The SDK or API sends consented activity events. Swapnice accepts them quickly, preserves per-customer order, and archives them asynchronously.
  </Step>

  <Step title="Read intelligence">
    The partner backend reads a resolved profile, underlying claims, and intent scores for that customer and purpose. Reads are synchronous and consent-aware.
  </Step>
</Steps>

## What is live in V1

| Surface                         | Status    | Partner use                                                      |
| ------------------------------- | --------- | ---------------------------------------------------------------- |
| OAuth 2.1 apps, PKCE, tokens    | Live      | Register an app and authenticate                                 |
| Connection sessions             | Live      | Link a partner customer to a Swapnice account                    |
| Consent receipts and revocation | Live      | Grant, inspect, and revoke purposes                              |
| Event ingest and batch ingest   | Live      | Send consented activity                                          |
| Customers, entries, ontologies  | Live      | Catalog the people and objects events refer to                   |
| Profiles, claims, and intents   | Live      | Read resolved facts and intent scores                            |
| Webhook endpoint registration   | Live      | Configure delivery destinations                                  |
| Webhook delivery                | Near-term | Push `event.processed`, `consent.revoked`, and `profile.updated` |

<Note>
  CRUD endpoints are infrastructure. The product partners integrate for is consented profile intelligence: resolved facts, provenance, and intent scores on top of the same event stream.
</Note>

## Implementation requirements

A V1 integration needs:

* A confidential partner backend that can store `client_id` and `client_secret`
* HTTPS redirect URIs registered exactly (no production wildcards)
* PKCE (`S256`) for authorization-code exchange
* An idempotency key on every mutating request
* A consent receipt before events are accepted
* Scopes that match the calls you will make (`events:write`, `consent:write`, `profile:read`, and so on)

The [integration guide](/partners/integration) walks through each step with sample TypeScript, Python, and cURL.

## Environments

| Environment | Base URL                           | Use                                         |
| ----------- | ---------------------------------- | ------------------------------------------- |
| Sandbox     | `https://api.sandbox.swapnice.com` | Integration, fixtures, and pilot testing    |
| Production  | `https://api.swapnice.com`         | Live consented traffic after go-live review |

Sandbox credentials and a test app are issued during onboarding. See [sandbox and testing](/partners/sandbox).

## Related

* [API overview](/partners/api-overview) and the generated [API reference](/partners/api-overview)