Provisioning - Corsair

Provisioning creates the database rows, DEKs, and credential slots Corsair needs before a tenant can connect. The same logic runs two ways: setupCorsair from your backend (on signup, in production) and pnpm corsair setup from the CLI (local and ops). Both are idempotent — they skip rows that already exist.

Data model

corsair_integrations   ← one row per plugin in createCorsair({ plugins })
corsair_accounts       ← one row per (tenant, plugin with an authType)

Layer	Table	Scope	Holds
Integration	`corsair_integrations`	Shared	OAuth app creds: `client_id`, `client_secret`, `redirect_url`
Account	`corsair_accounts`	Per tenant	API keys, OAuth tokens, refresh tokens
Tenant	(no table)	Your ID string	Materializes once account rows exist

Account rows are created only for plugins with an authType (api_key, oauth_2, bot_token). A tenant is any stable ID you choose — user id, org id, workspace slug.

setupCorsair

Call it from your backend, most often on signup — no deploy per tenant.

onboarding.ts

import { setupCorsair } from 'corsair';
import { corsair } from '@/server/corsair';

export async function onUserCreated(userId: string) {
    await setupCorsair(corsair, { tenantId: userId });
}

The same call covers single-tenant, credentials, and backfill:

// Single-tenant → provisions "default"
await setupCorsair(corsair);

// Multi-tenant → provision a tenant, seed a credential, backfill data
await setupCorsair(corsair, {
    tenantId: 'workspace_123',
    credentials: { linear: { api_key: process.env.LINEAR_KEY! } },
    backfill: true,
});

It returns a log string and skips existing rows.

What it creates

Creates	Does not touch
`corsair_accounts` per auth-type plugin	New plugins (needs a code change)
Account DEKs	OAuth tokens (arrive on connect)
`corsair_integrations` rows if missing	Integration creds (set those explicitly)

CLI

Same provisioning from the terminal — for local setup and ops:

# Single-tenant
pnpm corsair setup
pnpm corsair setup --slack api_key=xoxb-... --linear api_key=lin_api_...

# Multi-tenant — account rows + account credentials
pnpm corsair setup --tenant=workspace_123 --linear api_key=lin_api_...

# Integration-level OAuth app creds — no --tenant, even on multi-tenant
pnpm corsair setup --gmail client_id=... client_secret=...

Flag	Effect
`--tenant <id>`	Account rows + account credentials
`--<plugin> field=value`	Inline credentials
`--backfill`	Seed data (`setup/backfill.config.ts`); needs `--tenant` on multi-tenant

Credentials

Integration-level — shared OAuth app creds, one per plugin:

await corsair.keys.gmail.set_client_id('...');
await corsair.keys.gmail.set_client_secret('...');

Account-level — per tenant, for api_key / bot_token fields and OAuth tokens:

// multi-tenant
await corsair.withTenant('user_abc').linear.keys.set_api_key('lin_api_...');

// single-tenant
await corsair.linear.keys.set_api_key('lin_api_...');

keys.set_*() needs an account row first — run setupCorsair({ tenantId }) before setting API keys.

Multi-tenant: passing integration fields together with a tenantId in setupCorsair({ credentials }) throws. Set integration creds without a tenantId.

Multi-tenant

corsair.ts

export const corsair = createCorsair({
    multiTenancy: true,
    plugins: [github(), linear()],
    database: db,
    kek: process.env.CORSAIR_KEK!,
});

Task	`--tenant` / `tenantId`
Integration rows + OAuth app creds	Omit
Account rows, account creds, backfill	Required

Every runtime call goes through corsair.withTenant(id). See Multi-tenancy.

OAuth

Provisioning does not run OAuth — it prepares the rows. Tokens arrive when a user connects. After integration creds are set:

pnpm corsair auth --plugin=gmail --tenant=workspace_123

Or in app code, processOAuthCallback stores the tokens and creates the account row lazily if missing. This is the OAuth-only path — you can skip setupCorsair({ tenantId }) on signup and let the first connect provision the row. API keys still need setupCorsair first.

Adding a plugin later

Plugins come from createCorsair({ plugins: [...] }), so adding one is a code change and deploy. After deploying:

pnpm corsair setup                                    # integration row (+ default account, single-tenant)
pnpm corsair setup --gmail client_id=... client_secret=...

Multi-tenant — provision the new plugin for existing tenants (each still authorizes it separately; rows are not copied):

for (const tenantId of await listActiveTenantIds()) {
    await setupCorsair(corsair, { tenantId });
}

Removing a plugin from code does not delete its database rows.

corsair.manage.tenants.create() records a tenant but does not create account rows — use setupCorsair or the CLI to provision.

​Data model

​setupCorsair

​What it creates

​CLI

​Credentials

​Multi-tenant

​OAuth

​Adding a plugin later

Data model

setupCorsair

What it creates

CLI

Credentials

Multi-tenant

OAuth

Adding a plugin later