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.

OAuth

Discover, authorize (JSON PKCE), token, introspect, revoke.

Apps

Register and update the partner OAuth application.

Connection sessions

Start the account-linking session and poll status.

Consent

Grant, list, inspect, and revoke purpose receipts.

Customers

Upsert your user. Use external_id on create.

Events

Ingest consented activity. Idempotency-Key required.

Profiles

Read resolved facts, claims, and intent scores.

Entries and ontologies

Catalog objects of intent and their field maps.

Webhooks

Register receivers for async processing updates.

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. Ordered calls: request walkthrough.

Scopes

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.

Errors

{
  "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.