---
name: knot
description: >
  Start here for any Knot integration. Explains how Knot works (server-side session,
  client-side SDK, webhooks, server API), shared setup (auth, base URLs, Knot-Version,
  dashboard), and which Knot skill or docs page to use for each product. Use when:
  (1) "integrate Knot", (2) "add Knot to my app", (3) "which Knot product/skill do I need",
  (4) "how does Knot work", (5) setting up Knot API credentials or environments,
  (6) working with CardSwitcher/Switch, TransactionLink/Transactions, SubscriptionManager,
  Vaulting/Vault, Shopping/Shop, or Detect and unsure where to start.
metadata:
  author: Knot
  version: "1.0"
---

# Knot

Knot connects apps to their users' online merchant accounts (Amazon, Netflix, Uber, etc.) so the app can read data from and write data to those accounts.

Every integration has the same four parts:

1. **Create a session** on your server: `POST /session/create` with a `type` and your `external_user_id`.
2. **Open the SDK** in your client with that session. The SDK handles login, MFA, and errors while the user links a merchant account.
3. **Receive webhooks** on your server (for example `AUTHENTICATED`, `NEW_TRANSACTIONS_AVAILABLE`, `CARD_UPDATED`).
4. **Call the API** from your server to read or write data for the linked account.

## Pick a product

| Product (docs name / newer name) | Session `type` | Skill to use | Docs |
| --- | --- | --- | --- |
| CardSwitcher / Switch: update the user's card on file at merchants | `card_switcher` (requires `card_id`) | `knot-card-switcher` | [Quickstart](https://docs.knotapi.com/card-switcher/quickstart.md) |
| TransactionLink / Transactions: SKU-level transaction data | `transaction_link` | `knot-transaction-link` (new build), `knot-sync-transactions` (accounts already linked), `knot-prototype-transactions` (dev sample data only) | [Quickstart](https://docs.knotapi.com/transaction-link/quickstart.md) |
| SubscriptionManager / Subscriptions: subscription data and cancellation | `link` or `card_switcher` | `knot-subscriptions` | [Quickstart](https://docs.knotapi.com/subscription-manager/quickstart.md) |
| Vaulting / Vault: set a digital wallet as the default payment method | `vault` | None yet | [Quickstart](https://docs.knotapi.com/vaulting/quickstart.md) |
| Shopping / Shop: build carts and check out at merchants | `link` | `knot-prototype-shopping` (dev prototyping only) | [Quickstart](https://docs.knotapi.com/shopping/quickstart.md) |
| Detect: find which merchant accounts a user has | Pass `email`/`phone_number` when creating a `card_switcher` session, call `POST /detect` standalone, or use `link` | None yet | [Quickstart](https://docs.knotapi.com/detect/quickstart.md) |

## Skills that apply to every product

- `knot-sdk`: install and open the Link SDK (iOS, Android, React Native, Flutter, Web).
- `knot-webhooks`: build and secure the webhook endpoint, verify `Knot-Signature`, and route events.

## Shared setup

**Credentials.** Get the `client_id` and `secret` for each environment from the [Knot Dashboard](https://dashboard.knotapi.com/developers/keys). Authenticate every request with HTTP basic auth, sending `Authorization: Basic base64(client_id:secret)`. Keep the secret on your server only. It is also the key for verifying webhook signatures.

**Base URLs.**

| Environment | URL |
| --- | --- |
| Development | `https://development.knotapi.com` |
| Production | `https://production.knotapi.com` |

Development and production have separate credentials, and the SDK `environment` must match the environment the session was created in.

**Versioning.** Send a `Knot-Version` header on every request. Without it, requests default to version `2.0`. See [Versioning](https://docs.knotapi.com/api-reference/versioning.md).

**Users.** `external_user_id` is your own stable ID for the user. Knot scopes linked accounts, webhooks, and data to it, so reuse the same value for the same user.

**Sessions.** Create a new session each time you open the SDK. Sessions expire after 30 minutes. When the SDK emits `REFRESH_SESSION_REQUEST`, call `POST /session/extend`.

**Webhooks.** Add endpoint URLs per environment under [Dashboard → Developers → Webhooks](https://dashboard.knotapi.com/developers/webhooks).
- Return `200` within 10 seconds, then process asynchronously. Knot retries a non-200 or timed-out delivery up to two more times, so deduplicate.
- Verify the `Knot-Signature` header: an HMAC-SHA256 over the specified headers and body fields using your secret, base64-encoded. See [Webhooks](https://docs.knotapi.com/webhooks.md) for the exact string to sign.
- Ignore event types you don't recognize. Knot adds new events without a version bump.
- Session `metadata` (up to 10 keys) is echoed in every webhook for that session. Use it to correlate events with your internal IDs.

**Merchants.** Use `POST /merchant/list` to get the merchants available to you, filtering with `platform` and `search` if needed. Its `type` values are product names: `card_switcher`, `transaction_link`, `shopping`, `vault`, `subscription_manager`, or `cancel`. These are not the same as session types. See [Retrieving and listing merchants](https://docs.knotapi.com/link/retrieving-and-listing-merchants.md).

## Test in development

- Log in through the SDK with the test credentials `user_good` / `pass_good`. Each product's testing page lists other credentials for exercising MFA and failure paths.
- `POST /development/accounts/link` links a merchant account without the SDK, so you can test server-side flows and webhooks directly.
- Testing guides: [CardSwitcher](https://docs.knotapi.com/card-switcher/testing.md), [TransactionLink](https://docs.knotapi.com/transaction-link/testing.md), [Vaulting](https://docs.knotapi.com/vaulting/testing.md), [Shopping](https://docs.knotapi.com/shopping/testing.md).

## Before going live

Work through the [Launch checklist](https://docs.knotapi.com/launch-checklist.md). It covers production credentials and base URL, SDK environment, a new session per SDK open, the production webhook URL, and removing test credentials.

## Finding anything else

- Every docs page is available as Markdown by appending `.md` to its URL.
- [docs.knotapi.com/llms.txt](https://docs.knotapi.com/llms.txt) indexes every page.
- The full API spec is at [docs.knotapi.com/api-reference/openapi.json](https://docs.knotapi.com/api-reference/openapi.json).
- If the Knot docs MCP server (`https://docs.knotapi.com/mcp`) is connected, use its search tool before guessing an endpoint, field, or event name.