Skip to main content
Corsair runs entirely in your own app. A few things, though, need a stable public URL that a third party can reach: OAuth callbacks and approval pages. In a self-hosted setup you build and host those yourself. Hub is an optional hosted relay that provides them for you so you can skip the boilerplate. Hub is not a separate product or a separate SDK. It is the same createCorsair instance with one extra config block. Leave it out and you run fully self-hosted (the default). Add it and Corsair routes the public-URL surfaces through Corsair’s hosted endpoint.
corsair.ts
export const corsair = createCorsair({
    plugins: [github(), slack()],
    database: db,
    kek: process.env.CORSAIR_KEK!,
    hub: {
        projectApiKey: process.env.CORSAIR_API_KEY!,
        signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
    },
});
Self-hosted (manual) is the default and is fully featured. Hub is a convenience upgrade, not a requirement. See Manual or Hub for a side-by-side.

​
Hub stores none of your credentials

This is the part to internalize first: Hub is a relay, not a credential store. It does not keep your users’ access or refresh tokens. Tokens pass through the relay and are persisted only in your database, under your KEK. Compromising the relay exposes no credentials, because there are none there to expose. The same envelope encryption described in Authentication still applies. Each connection gets its own DEK, encrypted with your KEK, and the plaintext credential never lives anywhere but your database at runtime.

​
What Hub provides

Three surfaces normally need a public URL. Hub hosts all three:

OAuth callbacks

Register one callback URL with the provider. Hub holds it for both development and production. No more swapping redirect URIs between environments.

Hosted connect page

When an action needs a connection the user has not made yet, call createLink() to mint a Hub sign-in link. Hub hosts the connect page, so there is none to build. The user connects and retries.

Approval UI

For gated permissions, the SDK generates a link to a hosted approve/deny page. You do not build a review UI.

​
Connecting an account

When an agent or app hits an action that needs a connection the user has not made yet, the call throws an auth-missing error. You call createLink() to mint a Hub sign-in link and send the user to it. Hub hosts the connect page, so there is no “connect this first” UI to build. The user follows the link, connects, and retries the original action. You can also copy sign-in links from the Hub dashboard without writing code.

​
One callback, two environments

In a self-hosted setup, the OAuth redirect URI you register with each provider has to match the environment that is running, so you end up juggling separate provider apps (or rewriting redirect URIs) for local and production. With Hub you register one callback URL with the provider. Hub receives the callback and delivers the result to your app. Development and production use separate API keys and different delivery paths — see Environments for why (browser redirect locally, signed POST in production).

​
Turning Hub on

Set up a project in the Hub dashboard, then pass the hub block to createCorsair.
1

Create an organization and project

Sign in to the dashboard, create an organization, then create your first project. You get development and production environments automatically.
2

Copy development credentials

Open the Keys tab (development environment). Add the API key and signing secret to your local env. Use development keys locally; switch to production keys when you deploy.
.env.local
CORSAIR_API_KEY=ck_dev_...
CORSAIR_SIGNING_SECRET=...
CORSAIR_KEK=...
3

Register the OAuth redirect URL

Register https://auth.corsair.dev/oauth/callback in each OAuth provider console (GitHub, Google, etc.). This is the single callback Hub holds for every environment.
4

Mount the handler and run locally

Mount toNextJsHandler at /api/corsair. In development, Hub auto-detects your localhost delivery URL — no dashboard registration needed.
5

Activate production when you deploy

Switch to the production environment in the dashboard, register your public HTTPS delivery URL, and set ck_prod_… credentials in your deployed env. See Environments.
The hub block carries two required fields:
FieldPurpose
projectApiKeyIdentifies your project and environment (ck_dev_… or ck_prod_…)
signingSecretVerifies signed deliveries so only your app accepts them
Optional: apiUrl (self-hosted Hub API), oauthCallbackUrl (override callback URL). Mount the handler once and it serves both Hub delivery and the management API:
app/api/corsair/[[...path]]/route.ts
import { toNextJsHandler } from "corsair";
import { corsair } from "@/server";

export const { GET, POST, OPTIONS } = toNextJsHandler(corsair, {
    basePath: "/api/corsair",
});
From there, minting a connect link is identical to the self-hosted path. The same createLink API is used in both modes; only where the link points changes. See Connect / OAuth for the reference.

​
When to use Hub

Reach for Hub when you do not want to build and host connect pages and approval UIs, or when you want one provider callback to cover local development and production. Stay self-hosted when you want full control of those surfaces or cannot add an external dependency in the auth path.
Hub does not change how your agents call APIs. corsair.slack.api.*, withTenant, hooks, and the database layer all behave the same. Hub only affects the public-URL surfaces.

​
What’s next

Environments

Development vs production keys and delivery.

Hub dashboard

Connections, sign-in links, and production activation.

Manual or Hub

A side-by-side of what each mode requires you to build.

Delivery URLs

Browser redirect vs signed POST delivery.