Skip to main content
POST
/
session
/
create
cURL
curl --request POST \
  --url https://development.knotapi.com/session/create \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "card_switcher",
  "external_user_id": "123abc",
  "card_id": "81n9al10a0ayn13",
  "email": "ada.lovelace@gmail.com",
  "phone_number": "+11234567890",
  "processor_token": null,
  "metadata": {
    "reference_token": "abc123",
    "trace_id": "def456"
  }
}
'
{
  "session": "915efe72-5136-4652-z91q-d9d48003c102"
}

Documentation Index

Fetch the complete documentation index at: https://docs.knotapi.com/llms.txt

Use this file to discover all available pages before exploring further.

The value you receive in this endpoint should be subsequently passed into KnotConfiguration class of the SDK during initialization. Sessions last 30 minutes. It is best practice to create a new session each time you initialize the SDK and not log the session in any internal or 3rd party tooling.

Authorizations

​
Authorization
string
header
required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password. Use your client_id as the username and your secret as the password value.

Body

application/json

The input parameters required for creating a session.

​
type
enum<string>
required

Product to associate the session with.

Available options:
card_switcher,
transaction_link,
link,
vault
Example:

"card_switcher"

​
external_user_id
string
required

Your unique identifier for the user.

Example:

"123abc"

​
card_id
string | null

Your unique identifier for a specific card. Required when type = card_switcher. Optionally accepted when type = vault.

Example:

"81n9al10a0ayn13"

​
email
string | null

User's email address. When provided, Knot will automatically detect the user's online merchant accounts to personalize the experience in the SDK.

Example:

"ada.lovelace@gmail.com"

​
phone_number
string | null

User's phone number in E.164 format. When provided, Knot will automatically detect the user's online merchant accounts to personalize the experience in the SDK.

Example:

"+11234567890"

​
processor_token
string | null

Plaid processor_token if using transaction data from Plaid to detect merchants.

​
metadata
object

Optional key-value pairs to include in webhook payloads. Maximum 10 keys, 500 characters per value.

Example:
{
  "reference_token": "abc123",
  "trace_id": "def456"
}

Response

Successful request.

​
session
string

A session.

Example:

"915efe72-5136-4652-z91q-d9d48003c102"