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

# API overview

> Partner API contract, authentication, and every public route.

The Partner API is documented from `openapi.yaml`. Each group below has a short guide plus a playground page for every route.

Base URLs:

* Sandbox: `https://api.sandbox.swapnice.com`
* Production: `https://api.swapnice.com`

Public fields use descriptive names. Compact consumer-app storage keys (`c0`, `p0`, and similar) are internal and are not part of this API.

<CardGroup cols={2}>
  <Card title="OAuth" icon="key" href="/partners/api/oauth">
    Discover, authorize (JSON PKCE), token, introspect, revoke.
  </Card>

  <Card title="Apps" icon="grid-2" href="/partners/api/apps">
    Register and update the partner OAuth application.
  </Card>

  <Card title="Connection sessions" icon="link" href="/partners/api/connections">
    Start the account-linking session and poll status.
  </Card>

  <Card title="Consent" icon="shield-check" href="/partners/api/consent">
    Grant, list, inspect, and revoke purpose receipts.
  </Card>

  <Card title="Customers" icon="user" href="/partners/api/customers">
    Upsert your user. Use `external_id` on create.
  </Card>

  <Card title="Events" icon="bolt" href="/partners/api/events">
    Ingest consented activity. `Idempotency-Key` required.
  </Card>

  <Card title="Profiles" icon="id-card" href="/partners/api/profiles">
    Read resolved facts, claims, and intent scores.
  </Card>

  <Card title="Entries and ontologies" icon="layer-group" href="/partners/api/catalog">
    Catalog objects of intent and their field maps.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/partners/api/webhooks">
    Register receivers for async processing updates.
  </Card>
</CardGroup>

## Authentication

Most routes require a Bearer access token from the OAuth 2.1 authorization-code + PKCE flow. App registration uses a separate registration key.

| Mechanism                              | Used for                              |
| -------------------------------------- | ------------------------------------- |
| `Authorization: Bearer <access_token>` | Partner API calls                     |
| PKCE `S256`                            | `/oauth/authorize` and `/oauth/token` |
| `Idempotency-Key`                      | All mutating `/v1` routes             |
| App registration key                   | `POST /v1/apps` (issued by Swapnice)  |

Tokens are short-lived (\~15 minutes). Secrets and tokens are hashed at rest. Redirect URIs must match exactly.

Full narrative: [authentication](/partners/authentication). Ordered calls: [request walkthrough](/partners/request-walkthrough).

## Scopes

```text theme={null}
apps:read apps:write
connections:read connections:write
consent:read consent:write
customers:read customers:write
events:read events:write
profile:read claims:read intents:read
entries:read entries:write
ontologies:read ontologies:write
webhooks:read webhooks:write
tokens:introspect tokens:revoke
workflows:read
```

Request the smallest set that matches your calls. See [scope templates](/partners/integration#recommended-scope-templates).

## Errors

```json theme={null}
{
  "error": {
    "code": "consent_required",
    "message": "Effective consent does not allow this profile read.",
    "request_id": "req_3e19c0"
  }
}
```

Authorization failures stay generic. Response bodies do not include secrets or private wallet data.

## Playground

Open any route in this tab and send requests to **sandbox** with a token from your issued sandbox app. Do not point the playground at production.