Quick start

Hub hosts the OAuth connect, approval, and webhook surfaces, so there are no connect pages, callback routes, or per-environment redirect URIs to build. Credentials are encrypted and stored in your own database. Hub stores none.

Install

npm install corsair @corsair-dev/github

yarn add corsair @corsair-dev/github

pnpm install corsair @corsair-dev/github

bun add corsair @corsair-dev/github

@corsair-dev/github is one plugin. Every service is its own @corsair-dev/* package. Find the one you need, and its exact install id, in the Plugins catalog.

Set your environment

Create a project in the Hub dashboard and copy the development API key and signing secret. Then generate a KEK. Corsair encrypts every stored credential with it:

.env

CORSAIR_KEK=your-generated-kek
CORSAIR_DEV_API_KEY=ck_dev_...
CORSAIR_DEV_SIGNING_SECRET=...

Keep your KEK safe. Lose it and you lose access to every stored credential. Treat it like a root password.

Create the database

Corsair stores data in five tables. SQLite is the fastest way to start:

npm install better-sqlite3

yarn add better-sqlite3

pnpm install better-sqlite3

bun add better-sqlite3

View migration SQL

migration.sql

CREATE TABLE IF NOT EXISTS corsair_integrations (
    id TEXT PRIMARY KEY,
    created_at INTEGER NOT NULL,
    updated_at INTEGER NOT NULL,
    name TEXT NOT NULL,
    config TEXT NOT NULL DEFAULT '{}',
    dek TEXT NULL
);

CREATE TABLE IF NOT EXISTS corsair_accounts (
    id TEXT PRIMARY KEY,
    created_at INTEGER NOT NULL,
    updated_at INTEGER NOT NULL,
    tenant_id TEXT NOT NULL,
    integration_id TEXT NOT NULL,
    config TEXT NOT NULL DEFAULT '{}',
    dek TEXT NULL,
    FOREIGN KEY (integration_id) REFERENCES corsair_integrations(id)
);

CREATE TABLE IF NOT EXISTS corsair_entities (
    id TEXT PRIMARY KEY,
    created_at INTEGER NOT NULL,
    updated_at INTEGER NOT NULL,
    account_id TEXT NOT NULL,
    entity_id TEXT NOT NULL,
    entity_type TEXT NOT NULL,
    version TEXT NOT NULL,
    data TEXT NOT NULL DEFAULT '{}',
    FOREIGN KEY (account_id) REFERENCES corsair_accounts(id)
);

CREATE TABLE IF NOT EXISTS corsair_events (
    id TEXT PRIMARY KEY,
    created_at INTEGER NOT NULL,
    updated_at INTEGER NOT NULL,
    account_id TEXT NOT NULL,
    event_type TEXT NOT NULL,
    payload TEXT NOT NULL DEFAULT '{}',
    status TEXT,
    FOREIGN KEY (account_id) REFERENCES corsair_accounts(id)
);

CREATE TABLE IF NOT EXISTS corsair_permissions (
    id TEXT PRIMARY KEY,
    created_at INTEGER NOT NULL,
    updated_at INTEGER NOT NULL,
    token TEXT NOT NULL,
    plugin TEXT NOT NULL,
    endpoint TEXT NOT NULL,
    args TEXT NOT NULL,
    tenant_id TEXT NOT NULL,
    status TEXT NOT NULL DEFAULT 'pending',
    expires_at TEXT NOT NULL,
    error TEXT
);

macOS / Linux
Windows (PowerShell)

sqlite3 corsair.db < migration.sql

Get-Content migration.sql | sqlite3 corsair.db

Using Postgres, Drizzle, or Prisma instead? See Database for each option.

Configure Corsair

Wire your database, KEK, and Hub keys together in src/server/corsair.ts:

src/server/corsair.ts

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

const db = new Database('corsair.db');

export const corsair = createCorsair({
    plugins: [github({ authType: 'managed' })],
    database: db,
    kek: process.env.CORSAIR_KEK!,
    multiTenancy: true, // gives every user their own credentials; enables corsair.withTenant(id)
    hub: {
        projectApiKey: process.env.CORSAIR_DEV_API_KEY!,
        signingSecret: process.env.CORSAIR_DEV_SIGNING_SECRET!,
    },
});

Mount the handler once. It serves Hub delivery and the management API. In development, Hub auto-detects your localhost delivery URL:

app/api/corsair/[[...path]]/route.ts

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

export const { GET, POST, OPTIONS } = toNextJsHandler(corsair, {
    basePath: '/api/corsair',
});

This quick-start uses Next.js. The instance above is the same on every framework; only the mount line changes. See Frameworks for Express, Node, SvelteKit, Hono, and the rest.

Add more plugins later, like slack(), linear(), or gmail(), by appending to the array.

Connect and call

Mint a connect link and send the user to it. Hub hosts the connect page and delivers the result back to your app, with no connect page or OAuth callback to build:

connect.ts

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

Once connected, call any endpoint. Responses are also cached in your database for instant reads:

usage.ts

const repos = await corsair.github.api.repositories.list({});

Want an agent to call endpoints on its own? See MCP Adapters.

Run it

npm run dev

Load your app so the mounted route gets its first hit. That request registers your delivery URL with Hub, and the App sync dot in the dashboard header turns green. A green dot means Hub can reach your app and the connect flow is live.

What’s next

Use with AI

Give an agent the three Corsair tools and let it discover and call any endpoint.

Hub overview

How the relay works, and why Hub stores none of your credentials.

Environments

Development vs production keys. Switch to production when you deploy.

Multi-tenancy

Building a product? Flip one flag and every user gets their own data and credentials.

Database options

Postgres, Drizzle, Prisma, and the five tables Corsair uses.

Provisioning

Seed credentials and provision tenants from the corsair CLI or setupCorsair.

Get Started

Frameworks

Adapters

Workflows (beta)

Reference

Install

Set your environment

Create the database

Configure Corsair

Connect and call

Run it

What’s next

Use with AI

Hub overview

Environments

Multi-tenancy

Database options

Provisioning

​Install

​Set your environment

​Create the database

​Configure Corsair

​Connect and call

​Run it

​What’s next

Use with AI

Hub overview

Environments

Multi-tenancy

Database options

Provisioning

Install

Set your environment

Create the database

Configure Corsair

Connect and call

Run it

What’s next