SDK Session Bootstrap: Exchange Key for Client Token

Before using the JS SDK in the browser, your server must exchange your private API key for a short-lived JWT client token. This token is what the browser receives — your raw private key never leaves your server. Each token is scoped to a single checkout session and expires after 30 minutes.

Create a session on your server

Call POST /sdk/session from your backend with your private API key in the Authorization header.

curl -X POST https://api.therius.io/v1/sdk/session \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "customerId": "customer-42", "country": "US" }'

The response includes the clientToken and its lifetime in seconds:

{
  "clientToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 1800
}

Pass the token to the browser

Deliver clientToken to your front-end. Common approaches include:

Inline JSON — embed it in your HTML template when the page is server-rendered.
API response — return it from a lightweight /api/checkout-session endpoint that your SPA calls on page load.

The browser does not need to decode or inspect the token — it passes it directly to new TheriusSDK({ clientToken }).

Optional request parameters

Parameter	Type	Description
`country`	string	Two-letter ISO country code. Required for a full checkout session with a `sessionId`.
`customerId`	string	Associates the session with a returning shopper. Enables saved-card features.
`amount`	object	Pre-fills the session amount — useful for wallet payment sheets.
`currency`	string	Three-letter ISO currency code paired with `amount`.
`orderCode`	string	Your internal order reference, attached to the session for reconciliation.
`cardOnFile`	object	Declares this session’s checkout starts a stored-credential mandate — see Merchant-managed subscriptions below. Requires `customerId`.

Merchant-managed subscriptions

If you run your own recurring billing outside the Therius Subscriptions API — for example, a one-time checkout that should establish a card-on-file mandate you bill against yourself later — pass cardOnFile when creating the session, instead of configuring anything in the Checkout Builder:

curl -X POST https://api.therius.io/v1/sdk/session \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
        "customerId": "customer-42",
        "country": "US",
        "cardOnFile": { "type": "recurring" }
      }'

When cardOnFile is set:

The Checkout Widget skips the optional “save my card” checkbox entirely and shows a fixed disclosure (“Your card will be saved for future charges”) instead — there is nothing for the shopper to opt into, since you already declared the intent server-side.
The resulting charge is tokenized and tagged with the given stored-credential fields (usage/initiatedBy/type, see Stored Credentials) unconditionally, regardless of anything the browser sends — the signed session token is the source of truth, not the request body.
customerId is required — there must be a shopper to attribute the saved card to.

If you omit cardOnFile, the session behaves exactly as before: the checkout follows whatever the Checkout Builder’s “save my card” (vault-consent) setting says, and any resulting saved card is a plain card-on-file, not a recurring mandate.

There used to be a separate “Starts a merchant-managed subscription” checkbox in the Checkout Builder. It has been removed — this is now a per-transaction, server-controlled setting instead of a static per-checkout-config flag, so a shopper can never see (or suppress) the wrong consent state for a given session.

Initialize the SDK in the browser

Once the browser has the token, initialize the SDK:

import { TheriusSDK } from '@therius/sdk'

const sdk = new TheriusSDK({ clientToken })

The SDK validates the token immediately. If the token is missing or malformed, TheriusSDK throws synchronously.

Token lifetime

Client tokens expire after 30 minutes. Create a fresh token for each new checkout session — do not cache and reuse tokens across sessions or page loads.

Never call POST /sdk/session from the browser. It requires your private API key (prv_production_...). Exposing that key client-side would allow anyone to create sessions and make charges against your account. Always make this call from your backend only.

Reference

See the POST /sdk/session API reference for the full field reference, including error codes and validation rules.

Overview

Card Collection

Wallets & More

SDK Session Bootstrap: Exchange Key for Client Token

Create a session on your server

Pass the token to the browser

Optional request parameters

Merchant-managed subscriptions

Initialize the SDK in the browser

Token lifetime

Reference

​Create a session on your server

​Pass the token to the browser

​Optional request parameters

​Merchant-managed subscriptions

​Initialize the SDK in the browser

​Token lifetime

​Reference

Create a session on your server

Pass the token to the browser

Optional request parameters

Merchant-managed subscriptions

Initialize the SDK in the browser

Token lifetime

Reference