OAuth & External APIs

OAuth & External APIs

OAuth 2.0 authentication for external services

OAuthManager class

📍 src/connectors/oauth/OAuthManager.ts:13

constructor(config: OAuthConfig)

async getToken(userId?: string, accountId?: string): Promise<string>

async refreshToken(userId?: string, accountId?: string): Promise<string>

async isTokenValid(userId?: string, accountId?: string): Promise<boolean>

async startAuthFlow(userId?: string, accountId?: string): Promise<string>

async handleCallback(callbackUrl: string, userId?: string, accountId?: string): Promise<OAuthCallbackResult>

async revokeToken(revocationUrl?: string, userId?: string, accountId?: string): Promise<void>

async listAccounts(userId?: string): Promise<string[]>

async rekeyAccount(userId: string, oldAccountId: string, newAccountId: string): Promise<boolean>

async removeAccount(userId: string, accountId: string): Promise<boolean>

ApplyRefreshStrategyOptions interface

📍 src/connectors/vendors/helpers.ts:118

Options for applying provider refresh requirements to an existing configuration.

AuthTemplate interface

📍 src/connectors/vendors/types.ts:44

Authentication template for a vendor Defines a single authentication method (e.g., API key, OAuth user flow)

BuildAuthConfigOptions interface

📍 src/connectors/vendors/helpers.ts:181

Options for editing a same-method authorization-code configuration.

CreateConnectorOptions interface

📍 src/connectors/vendors/types.ts:212

Options for creating a connector from a template

ITokenStorage interface

📍 src/connectors/oauth/domain/ITokenStorage.ts:19

Token storage interface All implementations MUST encrypt tokens before storing

storeToken(key: string, token: StoredToken): Promise<void>;

getToken(key: string): Promise<StoredToken | null>;

deleteToken(key: string): Promise<void>;

hasToken(key: string): Promise<boolean>;

listKeys?(): Promise<string[]>;

OAuthCallbackResult interface

📍 src/connectors/oauth/types.ts:80

Result of one authorization-code exchange; never persisted by token storage.

OAuthConfig interface

📍 src/connectors/oauth/types.ts:9

OAuthConnectorAuth interface

📍 src/domain/entities/Connector.ts:36

OAuth 2.0 authentication for connectors Supports multiple OAuth flows

OptionField interface

📍 src/connectors/vendors/types.ts:117

Vendor-specific option field definition. Declares a configurable option that UI apps render as form fields. Values are stored in connector.config.options and accessed via connector.getOptions().

SimpleIcon interface

📍 src/connectors/vendors/logos.ts:11

Simple Icons icon data structure

type: string;
url?: string;

StoredToken interface

📍 src/connectors/oauth/types.ts:95

StoredToken interface

📍 src/connectors/oauth/domain/ITokenStorage.ts:6

Token storage interface (Clean Architecture - Domain Layer) All implementations must encrypt tokens at rest

VendorInfo interface

📍 src/connectors/vendors/helpers.ts:520

Get vendor template information for display

id: string;
name: string;
type: string;
description: string;
requiredFields: string[];
scopes?: string[];
scopeDescriptions?: Record<string, string>;

VendorLogo interface

📍 src/connectors/vendors/logos.ts:184

Vendor logo information

VendorRegistryEntry interface

📍 src/connectors/vendors/types.ts:179

Registry entry for a vendor (generated at build time)

VendorTemplate interface

📍 src/connectors/vendors/types.ts:144

Vendor template definition Complete configuration for a vendor's supported authentication methods

AuthTemplateField type

📍 src/connectors/vendors/types.ts:87

Known fields that can be required/optional in auth templates

type AuthTemplateField = | 'apiKey'
  | 'clientId'
  | 'clientSecret'
  | 'redirectUri'
  | 'scope'
  | 'privateKey'
  | 'privateKeyPath'
  | 'appId'
  | 'installationId'
  | 'tenantId'
  | 'username'
  | 'subject'
  | 'audience'
  | 'userScope'
  | 'accountId'
  | 'subdomain'
  | 'region'
  | 'accessKeyId'
  | 'secretAccessKey'
  | 'applicationKey'
  // Vendor-specific extra fields (stored in auth.extra)
  | 'appToken'
  | 'signingSecret'

OAuthFlow type

📍 src/connectors/oauth/types.ts:7

type OAuthFlow = 'authorization_code' | 'client_credentials' | 'jwt_bearer' | 'static_token'

RefreshStrategy type

📍 src/connectors/vendors/types.ts:33

How a vendor issues refresh tokens for authorization_code flows. Determines what (if anything) the library merges into authorize URLs to request renewal capability. Issuance still depends on provider policy and existing consent. Required for every authorization_code template — the registry initializer fails fast if absent.

• automatic: vendor issues a refresh token unconditionally (Discord, Asana, HubSpot, Stripe, QuickBooks, Box, Zoom, Pipedrive, Ramp, Atlassian-Bitbucket).
• never_expires: tokens don't expire (or have multi-year lifetime), no refresh ever needed (Notion, Linear, Airtable PAT, GitHub OAuth Apps, Slack classic bot tokens).
• scope: a specific scope token must be in the authorize request. Microsoft / Atlassian / GitLab use offline_access; Salesforce uses refresh_token; Twitter/X uses offline.access (note the dot). Force-merged on every authorize URL to survive operator scope overrides.
• auth_param: a query param must be on the authorize URL. Google uses access_type=offline; Dropbox uses token_access_type=offline. Stamped into the persisted authorizationParams.
• manual_setup: refresh tokens require out-of-band IdP / app config the library can't enforce (GitHub App "expire user tokens" toggle, Slack token rotation enable). Surfaces a warning at template-import time.

type RefreshStrategy = | { kind: 'automatic' }
  | { kind: 'never_expires' }
  | { kind: 'scope'; scope: string }
  | { kind: 'auth_param'; key: string; value: string }
  | { kind: 'manual_setup'; description: string }

TemplateCredentials type

📍 src/connectors/vendors/types.ts:205

Credentials provided by user when creating connector from template

type TemplateCredentials = {
  [K in AuthTemplateField]?: string;
}

applyRefreshStrategy function

📍 src/connectors/vendors/helpers.ts:136

Apply only a provider's refresh requirements. Pure and idempotent: configured API scopes and unrelated parameters (including prompt) are preserved. scope is authoritative, including an explicit empty string. When absent, fall back to authorizationParams.scope; remove that duplicate parameter from the returned patch so it cannot override edits or required scopes. With enforce enabled, a missing strategy is an error and the strategy's authorization parameter wins. Existing three-argument calls keep their operator-value precedence. This requests renewal capability; it does not guarantee a refresh token in every response or perform manual provider setup.

export function applyRefreshStrategy(
  scope: string | undefined,
  authorizationParams: Record<string, string> | undefined,
  strategy: RefreshStrategy | undefined,
  options: ApplyRefreshStrategyOptions = {},
): {
  scope: string;
  requiredScope: string | undefined;
  authorizationParams: Record<string, string> | undefined;
}

authenticatedFetch function

📍 src/connectors/authenticatedFetch.ts:51

Fetch with automatic authentication using connector's configured auth scheme

Same API as standard fetch(), but with additional authProvider and optional userId/accountId parameters. Authentication is handled automatically based on the connector's configuration:

• Bearer tokens (GitHub, Slack, Stripe)
• Bot tokens (Discord)
• Basic auth (Twilio, Zendesk)
• Custom headers (e.g., X-Shopify-Access-Token)

export async function authenticatedFetch(
  url: string | URL,
  options: RequestInit | undefined,
  authProvider: string,
  userId?: string,
  accountId?: string
): Promise<Response>

Example:

Single-user mode:

const response = await authenticatedFetch(
'https://graph.microsoft.com/v1.0/me',
{ method: 'GET' },
'microsoft'
);
const data = await response.json();

Multi-account mode:

const response = await authenticatedFetch(
'https://graph.microsoft.com/v1.0/me',
{ method: 'GET' },
'microsoft',
'alice',
'work'  // Use Alice's work Microsoft account
);

buildAuthConfig function

📍 src/connectors/vendors/helpers.ts:259

Build ConnectorAuth from a template and credentials. Creation uses template defaults. With existingAuth, preserve saved authorization-code settings and apply only the nonempty credential patch plus provider refresh requirements.

export function buildAuthConfig(
  authTemplate: AuthTemplate,
  credentials: TemplateCredentials,
  options: BuildAuthConfigOptions = {},
): ConnectorAuth

createAuthenticatedFetch function

📍 src/connectors/authenticatedFetch.ts:98

Create an authenticated fetch function bound to a specific connector and optionally a user/account

Useful for creating reusable fetch functions for a specific API and/or user. Uses connector's configured auth scheme (Bearer, Bot, Basic, custom headers).

export function createAuthenticatedFetch(
  authProvider: string,
  userId?: string,
  accountId?: string
): (url: string | URL, options?: RequestInit) => Promise<Response>

Example:

Single-user mode:

const msftFetch = createAuthenticatedFetch('microsoft');

// Use like normal fetch (auth automatic)
const me = await msftFetch('https://graph.microsoft.com/v1.0/me');
const emails = await msftFetch('https://graph.microsoft.com/v1.0/me/messages');

Multi-account mode:

// Create fetch for Alice's work Microsoft account
const workFetch = createAuthenticatedFetch('microsoft', 'alice', 'work');
const personalFetch = createAuthenticatedFetch('microsoft', 'alice', 'personal');

const workEmails = await workFetch('/me/messages');
const personalEmails = await personalFetch('/me/messages');

createConnectorFromTemplate function

📍 src/connectors/vendors/helpers.ts:452

Create a Connector from a vendor template

export function createConnectorFromTemplate(
  name: string,
  vendorId: string,
  authTemplateId: string,
  credentials: TemplateCredentials,
  options?: CreateConnectorOptions
): Connector

Example:

const connector = createConnectorFromTemplate(
  'my-github',
  'github',
  'pat',
  { apiKey: process.env.GITHUB_TOKEN }
);

extractNonSecretCredentials function

📍 src/connectors/vendors/helpers.ts:393

Extract non-secret credentials from a raw credentials dict. Used by ConnectorConfigStore.saveFromTemplate() to preserve template field values for round-trip editing without storing secrets.

export function extractNonSecretCredentials(
  authTemplate: AuthTemplate,
  credentials: TemplateCredentials,
): Record<string, string>

generateEncryptionKey function

📍 src/connectors/oauth/utils/encryption.ts:107

Generate a secure random encryption key Use this to generate OAUTH_ENCRYPTION_KEY for your .env file

export function generateEncryptionKey(): string

getAllVendorLogos function

📍 src/connectors/vendors/logos.ts:298

Get all available vendor logos

export function getAllVendorLogos(): Map<string, VendorLogo>

getAllVendorTemplates function

📍 src/connectors/vendors/helpers.ts:65

Get all vendor templates

export function getAllVendorTemplates(): VendorTemplate[]

getCredentialsSetupURL function

📍 src/connectors/vendors/helpers.ts:603

Get credentials setup URL for a vendor

export function getCredentialsSetupURL(vendorId: string): string | undefined

getDocsURL function

📍 src/connectors/vendors/helpers.ts:611

Get docs URL for a vendor

export function getDocsURL(vendorId: string): string | undefined

getVendorAuthTemplate function

📍 src/connectors/vendors/helpers.ts:77

Get auth template for a vendor

export function getVendorAuthTemplate(
  vendorId: string,
  authId: string
): AuthTemplate | undefined

getVendorColor function

📍 src/connectors/vendors/logos.ts:288

Get the brand color for a vendor

export function getVendorColor(vendorId: string): string | undefined

getVendorInfo function

📍 src/connectors/vendors/helpers.ts:540

Get vendor information suitable for display

export function getVendorInfo(vendorId: string): VendorInfo | undefined

getVendorLogo function

📍 src/connectors/vendors/logos.ts:227

Get logo for a vendor

export function getVendorLogo(vendorId: string): VendorLogo | undefined

Example:

const logo = getVendorLogo('github');
if (logo) {
  console.log(logo.svg);  // SVG content
  console.log(logo.hex);  // Brand color
}

getVendorLogoCdnUrl function

📍 src/connectors/vendors/logos.ts:330

Get CDN URL for a vendor's logo

export function getVendorLogoCdnUrl(vendorId: string, color?: string): string | undefined

getVendorLogoSvg function

📍 src/connectors/vendors/logos.ts:270

Get SVG content for a vendor logo

export function getVendorLogoSvg(vendorId: string, color?: string): string | undefined

getVendorTemplate function

📍 src/connectors/vendors/helpers.ts:53

Get vendor template by ID

export function getVendorTemplate(vendorId: string): VendorTemplate | undefined

hasVendorLogo function

📍 src/connectors/vendors/logos.ts:200

Check if a vendor has a logo available

export function hasVendorLogo(vendorId: string): boolean

listVendorIds function

📍 src/connectors/vendors/helpers.ts:89

List all vendor IDs

export function listVendorIds(): string[]

listVendors function

📍 src/connectors/vendors/helpers.ts:565

List all vendors with basic info

export function listVendors(): VendorInfo[]

listVendorsByAuthType function

📍 src/connectors/vendors/helpers.ts:594

List vendors that support a specific auth type

export function listVendorsByAuthType(authType: 'api_key' | 'oauth'): VendorInfo[]

listVendorsByCategory function

📍 src/connectors/vendors/helpers.ts:587

List vendors by category

export function listVendorsByCategory(category: string): VendorInfo[]

listVendorsWithLogos function

📍 src/connectors/vendors/logos.ts:314

List vendor IDs that have logos available

export function listVendorsWithLogos(): string[]

VENDOR_ICON_MAP const

📍 src/connectors/vendors/logos.ts:26

Mapping from our vendor IDs to Simple Icons slugs