Consent and account linking

How a partner customer is linked to a Swapnice account, which purposes exist, and how revocation works.

Swapnice treats consent as a first-class object, not a banner click. Events are rejected and purpose-scoped reads fail closed unless a receipt still grants that purpose.

Two identities, one link

Record	Who creates it	What it is
Partner customer	Your backend, via POST /v1/customers	Your user, keyed by external_id
Connection session	Your app, via POST /v1/connection-sessions	Short-lived link attempt
Swapnice account	The user, inside Swapnice	Their Swapnice identity
Consent receipt	Recorded after they accept	Purpose grants bound to that link

You never need the user’s global Swapnice user id to start. The connection session is the Plaid-Link-style step that binds the two records after the user authorizes.

A Swapnice consumer account can later have wallet or bank linking inside Swapnice. That stack is not part of the Partner API and is never returned to partners.

Connection session

const session = await swapnice.connectionSessions.create({
  customer_id: customer.id,
  requested_purposes: ["personalization", "analytics"],
  redirect_uri: process.env.SWAPNICE_REDIRECT_URI!,
});
// Open session.connection_url. Poll GET /v1/connection-sessions/:id

Statuses: created → authorized → completed, or expired / revoked.

Sessions expire. Do not reuse an expired session_id. Create a new one.

Consent receipt

After the user accepts, persist the receipt. This is what later events must cite.

{
  "receipt_id": "cr_44aa01",
  "customer_id": "cust_8f2a1c",
  "purposes": ["personalization", "analytics"],
  "status": "granted",
  "granted_at": "2026-08-26T16:02:12.000Z"
}

Include terms_version and privacy_policy_version so you can prove which policy the user saw.

Inspect current grants with GET /v1/customers/:id/effective-consent.

Purposes in product language

Purpose	What the user is allowing	Typical partner use	Default for a conservative app
account_linking	Connect this app account to Swapnice	Complete the link	Yes, during connect
personalization	Use my activity to improve this experience	Home shelf, recommendations	Yes
analytics	Use my activity in aggregate product analytics	Funnels, quality dashboards	Yes
support	Let this app debug my own connection	Break-fix	Yes
event_enrichment	Attach catalog context to my events	SKU / series metadata	Optional
profile_resolution	Include this signal when facts are resolved	Winner-vs-alternative profiles	Optional
measurement	Use my activity to understand product outcomes	Optional product-outcome reads	Explicit opt-in

A user who granted personalization has not granted every other purpose. The same event can be stored for one purpose and unusable for another.

Pilot recommendation: request personalization and analytics. Add other purposes only when the product actually uses them.

Revocation

await swapnice.consentReceipts.revoke(receiptId, {
  purposes: ["personalization"],
  reason: "user_request",
});

reason is one of user_request, partner_request, policy_change, account_disconnected, other.

What happens immediately:

• New events for a revoked purpose return consent_required
• Profile reads that pass that consent_purpose return 403
• The partner product must stop using that customer’s intelligence for the revoked purpose

The API accepts revoke synchronously (202 plus a workflow_id). Archive and workflow records update asynchronously. Poll GET /v1/workflows/:id.

You can revoke a subset of purposes or the entire receipt.

Collection notice

Your connect UI should say, in language the user understands:

1. Which app is asking
2. Which purposes, in the table above — not raw scope strings
3. That they can disconnect later
4. That they can revoke a purpose without deleting the rest of the connection

Swapnice can provide sample consent copy during onboarding. Do not invent a purpose that is not in the documented API enum.

What consent does not cover

Consent to the Partner API does not grant access to:

• Wallet, Dwolla, or Plaid credentials
• Government identification
• Precise home address
• Another partner’s users or raw events
• The right to resell the consolidated Swapnice profile

See data collection for what is transmitted after a grant.