Authentication & Request Conventions

Knit’s public API is versioned under /api/v1. Use https://api-prod.useknit.io for production traffic and https://api-dev.useknit.io for pre-production testing. Throughout the docs we refer to these as {{baseUrl}}; substitute whichever environment you are targeting when making a request.

Request & Response Shape

• Content-Type: all endpoints accept and return JSON. Example payloads in this documentation mirror what the API expects.

Authentication Options

All /api/v1/** routes accept the following credential types:

You may send both headers during migrations—the platform prioritises the bearer token and falls back to X-API-KEY if it is absent—but note that API keys are being deprecated, so plan to rely solely on OAuth going forward.

Getting an OAuth Access Token

1. In the Knit dashboard, navigate to Business → Developer → OAuth Clients and create (or rotate) a client. Copy the client ID and plain secret. No API call is required for this step.
2. Request a bearer token via the OAuth 2.0 client credentials grant:

curl --location '{{baseUrl}}/oauth/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "grant_type": "client_credentials",
    "client_id": "<client-id>",
    "client_secret": "<plain-secret>"
  }'

The response contains token_type, expires_in (default is 900 seconds), and access_token. Supply that token in the Authorization header for subsequent API calls.

Scopes

Scopes follow the resource:action pattern:

• collections:read, collections:write
• payouts:read, payouts:write
• wallets:read, wallets:write
• payout-wallets:read, payout-wallets:write
• * for full access (use sparingly)

Write scopes implicitly grant read access (e.g. payouts:write can also perform GET /api/v1/payouts). If a request reaches an endpoint without the required scope, the API returns 401 Insufficient permissions.

IP Whitelisting

Provide the outbound IP addresses of your servers in the dashboard and we’ll add them to your business whitelist. Any request coming from an IP that is not on that list is rejected with 401 IP address not whitelisted, so be sure to register staging/production IPs before going live.

Rate Limiting

Use the provided API keys or OAuth clients per application/service rather than sharing them between environments. This keeps credentials easy to rotate and limits blast radius if one integration needs to be paused.