Folk plugin

• Authentication: Use an API key from workspace settings under API. Pass it as a Bearer token (Authorization: Bearer <key>).
• Rate limits: Folk applies rate limits per user across two concurrent windows: a default limit of 600 requests per minute, and a burst limit of 20 requests per 2 seconds. The plugin automatically reads standard Retry-After headers on 429 responses.
• Idempotency: Modifying endpoints (POST, PATCH, DELETE) accept an optional idempotencyKey parameter that passes an Idempotency-Key header to safely retry requests without duplication.
• Custom fields: People and companies support customFieldValues mapped by group ID and custom field name.

• 33 typed API operations

Setup

npm install corsair @corsair-dev/folk better-sqlite3
npm install --save-dev @types/better-sqlite3

yarn add corsair @corsair-dev/folk better-sqlite3
yarn add --dev @types/better-sqlite3

pnpm install corsair @corsair-dev/folk better-sqlite3
pnpm install --save-dev @types/better-sqlite3

bun add corsair @corsair-dev/folk better-sqlite3
bun add --dev @types/better-sqlite3

import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { folk } from '@corsair-dev/folk';

export const corsair = createCorsair({
	plugins: [
		folk(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});

folk()

const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'folk',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.folk.api.people.list({ limit: 10 });

const tenant = corsair.withTenant('acme');
await tenant.folk.api.people.create({
	firstName: 'Jane',
	lastName: 'Doe',
	emails: ['jane.doe@example.com'],
});

What’s next