Authentication

OAuth flows, API keys, and bot tokens all go through the same credential handling. Corsair stores them encrypted and manages them across every tenant.

corsair.ts

import { createCorsair } from "corsair";
import { slack } from "@corsair-dev/slack";
import { linear } from "@corsair-dev/linear";

export const corsair = createCorsair({
    multiTenancy: true,
    plugins: [
        slack({
            authType: "api_key",
            credentials: { botToken: "xoxb-..." },
        }),
        linear({
            authType: "oauth_2",
            credentials: {
                clientId: process.env.LINEAR_CLIENT_ID,
                clientSecret: process.env.LINEAR_CLIENT_SECRET,
            },
        }),
    ],
});

Auth types

Choose the auth type for each integration:

API key

For integrations that use static API keys or bot tokens.

slack({
    authType: "api_key",
    credentials: { botToken: "xoxb-your-bot-token" },
})

OAuth 2.0

For integrations that require user authorization.

linear({
    authType: "oauth_2",
    credentials: {
        clientId: process.env.LINEAR_CLIENT_ID,
        clientSecret: process.env.LINEAR_CLIENT_SECRET,
    },
})

Managed

Corsair hosts the OAuth app, so you register nothing in the provider console. Enable it per plugin with authType: "managed". Available for managed plugins on Hub.

github({
    authType: "managed",
})

Automatic token refresh

When using OAuth, tokens expire. Corsair handles this automatically:

Before making a request, checks if the token is expired
If expired, uses the refresh token to get a new access token
Stores the new token and continues with the request

You never have to think about token rotation.

Envelope encryption

Corsair uses envelope encryption to protect credentials:

You set one KEK (Key Encryption Key) in your environment variables
Each connection gets its own DEK (Data Encryption Key)
All credentials are encrypted with the connection’s DEK
The DEK is encrypted with your KEK

.env

CORSAIR_KEK=your-key-encryption-key

Each connection has a different DEK, so compromising one connection’s key doesn’t expose others.

This holds whether you self-host or use Hub. Hub is a relay for connect, approval, and webhook surfaces; it stores none of your credentials. Encrypted tokens are persisted only in your database in both modes.

Bring Your Own KMS

If you’re using a Key Management Service (AWS KMS, Google Cloud KMS, etc.), you can opt out of Corsair’s built-in encryption.

corsair.ts

export const corsair = createCorsair({
    plugins: [
        slack({
            authType: "api_key",
            credentials: {
                // Pass your decrypted key directly
                botToken: await kms.decrypt(encryptedToken),
            },
        }),
    ],
});

Multi-tenant credentials

With multi-tenancy, each tenant has their own credentials stored securely.

example.ts

// Tenant A's Slack token
const tenantA = corsair.withTenant("tenant_a");
await tenantA.slack.api.messages.post({ ... });

// Tenant B's Slack token — completely separate
const tenantB = corsair.withTenant("tenant_b");
await tenantB.slack.api.messages.post({ ... });

Corsair retrieves the correct credentials for each tenant automatically.

Get Started

Frameworks

Adapters

Workflows (beta)

Reference

Auth types

API key

OAuth 2.0

Managed

Automatic token refresh

Envelope encryption

Bring Your Own KMS

Multi-tenant credentials

​Auth types

​API key

​OAuth 2.0

​Managed

​Automatic token refresh

​Envelope encryption

​Bring Your Own KMS

​Multi-tenant credentials

Auth types

API key

OAuth 2.0

Managed

Automatic token refresh

Envelope encryption

Bring Your Own KMS

Multi-tenant credentials