Quick Start

The quickest path to a working integration is Hub. It 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 still encrypted and stored in your own database — Hub stores none.

Want to host those surfaces yourself instead? Every step below is the same; swap the hub block for manual. See Manual or Hub.

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=...
APP_URL=http://localhost:3000

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 four 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)
);

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 'dotenv/config';
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!,
    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',
});

Add more plugins later — slack(), linear(), 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 — 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.

What’s next

Use with AI

Give an agent the four 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 four tables Corsair uses.

Provisioning

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

Get Started

Adapters

Hub

Concepts

Management API

Install

Set your environment

Create the database

Configure Corsair

Connect and call

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

​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

What’s next