Skip to main content
The Refold server SDK is a thin wrapper over the Refold API for your backend. It manages linked accounts, mints session tokens for your frontend, and triggers events, all with your API key held server-side. Use it as the backend half of every native integration. Your API key authenticates every call and must never reach the browser. The SDK keeps it on your server: your frontend gets a short-lived session token instead, and the SDK is where you mint that token.
The SDK targets the base URL https://app.refold.ai and sends your API key in the x-api-key header for you. Run it only on your server.

​
Prerequisites

​
Install the SDK

1

Install the package

Add the Refold Node.js SDK to your backend.
npm install @cobaltio/cobalt
TODO: confirm the published npm package name and import for the Refold-branded server SDK. The current package on npm is @cobaltio/cobalt and the client class is Cobalt. Verify whether a renamed Refold package exists before publishing.
2

Initialize the client

Create the client once at startup and read the API key from your environment.
Node.js
const Cobalt = require("@cobaltio/cobalt");

const client = new Cobalt({
  apiKey: process.env.REFOLD_API_KEY,
});
3

Verify the connection

Mint a session token for a test linked account to confirm the key and environment are correct.
Node.js
const { token } = await client.getTokenForLinkedAccount({
  linked_account_id: "demo-user-1",
});

console.log("Session token:", token);
For the full method list (linked accounts, tokens, config, and events), see the Node.js SDK reference.

​
Where the API key lives

Keep one rule: the API key stays on the server, and the browser only ever sees a session token.
  • Read the key from an environment variable, never a literal in source. The examples use process.env.REFOLD_API_KEY.
  • Use the test key in non-production environments and the live key in production. The key selects the environment. See Test vs production credentials.
  • Initialize one client per environment and reuse it across requests rather than constructing a new client per call.
Never ship your API key to the frontend or embed it in client code. If a key is exposed, rotate it in Settings > Credentials and redeploy.

​
Prefer the API directly?

The SDK is optional. Every operation is a plain HTTP call you can make from any backend with the base URL https://app.refold.ai and the x-api-key header.
cURL
curl -X POST "https://app.refold.ai/api/v2/public/session-token" \
  -H "x-api-key: $REFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "linked_account_id": "demo-user-1" }'
Output
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 599747,
  "refresh_expires_in": 2586947
}

​
Next steps

Create linked accounts

Create one account per customer and mint a session token for the frontend.

Node.js SDK reference

Every method, parameter, and return shape.

Trigger events

Start workflows from your backend when something happens in your app.

Make API proxy calls

Call a connected app’s API with the customer’s stored credentials.