Node SDK

Installation

npm install @authpipe/node

Configuration

import { Authpipe } from "@authpipe/node";

const authpipe = new Authpipe({
  apiKey: "sk_...",                          // Required
  baseUrl: "https://api.authpipe.dev",       // Optional (default)
  apiVersion: "2026-04-07",                  // Optional (default)
  cache: true,                               // Optional (default true)
  cacheTtlSeconds: 300,                      // Optional (default 300)
});

Option	Type	Default	Description
apiKey	string	—	Secret or publishable API key (required)
baseUrl	string	https://api.authpipe.dev	API base URL
apiVersion	string	2026-04-07	API version header
cache	boolean	true	Enable credential caching
cacheTtlSeconds	number	300	Cache TTL in seconds

Credentials

getCredential

Retrieve a valid credential for a provider + tenant combination. Auto-refreshes expired tokens.

const result = await authpipe.getCredential({
  provider: "slack",
  tenantId: "org_acme",
  userId: "user_jane",           // Optional
  installationId: "inst_123",    // Optional
  credentialFor: "any",          // Optional: "any" | "installation" | "user"
});

result.credential       // The access token or API key
result.credential_type  // "oauth_token" | "api_key" | "webhook_secret" | "cached"
result.source           // "connection" | "installation" | "cache"
result.expires_at       // Token expiry (optional)
result.scopes           // Granted scopes (optional)

storeCredential

Store an API key or webhook secret.

const result = await authpipe.storeCredential({
  provider: "sendgrid",
  tenantId: "org_acme",
  credentialType: "api_key",     // "api_key" | "webhook_secret"
  credential: "SG.xxxx",
  userId: "user_jane",           // Optional
  installationId: "inst_123",    // Optional
});

result.connection_id  // ID of the created/updated connection
result.status         // "active"

OAuth Sessions

createAuthSession

Create an OAuth authorization session for a user connection.

const session = await authpipe.createAuthSession({
  provider: "google",
  tenantId: "org_acme",
  redirectUrl: "https://yourapp.com/callback",
  userId: "user_jane",                          // Optional
  scopes: ["drive.readonly"],                   // Optional
  installationId: "inst_123",                   // Optional
  templateVariables: { shop: "acme-store" },    // Optional
});

session.session_id        // Session identifier
session.authorization_url // Redirect the user here

createInstallSession

Create an app installation session (Slack bot, GitHub App, etc.).

const session = await authpipe.createInstallSession({
  provider: "slack",
  tenantId: "org_acme",
  redirectUrl: "https://yourapp.com/installed",
  userId: "user_admin",                        // Optional
  permissions: ["channels:read", "chat:write"], // Optional
});

session.session_id
session.authorization_url

Connections

getConnection

const connection = await authpipe.getConnection("conn_abc123");

deleteConnection

Revoke a connection (soft delete).

await authpipe.deleteConnection("conn_abc123");

refreshConnection

Force an immediate token refresh.

const result = await authpipe.refreshConnection("conn_abc123");
result.refreshed   // boolean
result.expires_at  // new expiry (optional)

searchConnections

const resp = await authpipe.searchConnections({
  filter: {
    tenant_id: { eq: "org_acme" },
    status: { eq: "active" },
  },
  sort: [{ field: "connected_at", direction: "desc" }],
  cursor: "cursor_token",
  limit: 25,
});

resp.data        // Connection[]
resp.has_more    // boolean
resp.next_cursor // string (for next page)
resp.limit       // number

Installations

getInstallation

const installation = await authpipe.getInstallation("inst_abc123");

deleteInstallation

await authpipe.deleteInstallation("inst_abc123");

searchInstallations

const resp = await authpipe.searchInstallations({
  filter: { tenant_id: { eq: "org_acme" } },
});

Provider Configs

createProviderConfig

const config = await authpipe.createProviderConfig({
  provider_id: "slack",
  client_id: "your-client-id",
  client_secret: "your-client-secret",
  oauth_redirect_url: "https://api.authpipe.dev/oauth/callback",
  attachment: "user",  // "tenant" | "user"
  enabled: true,
  scopes: ["channels:read"],  // Optional
});

getProviderConfig

const config = await authpipe.getProviderConfig("pcfg_abc123");

updateProviderConfig

const config = await authpipe.updateProviderConfig("pcfg_abc123", {
  client_secret: "new-secret",     // Optional
  scopes: ["channels:read", "chat:write"], // Optional
  bot_scopes: ["chat:write"],      // Optional
  signing_key: "signing-secret",   // Optional
  enabled: true,                   // Optional
});

deleteProviderConfig

Cascades to all installations (which cascade-revoke their connections).

await authpipe.deleteProviderConfig("pcfg_abc123");

searchProviderConfigs

const resp = await authpipe.searchProviderConfigs({
  filter: { provider_id: { eq: "slack" } },
});

Providers (Catalog)

getProvider

const provider = await authpipe.getProvider("slack");

searchProviders

const resp = await authpipe.searchProviders({
  query: "email",
  filter: { category: { eq: "communication" } },
  limit: 10,
});

Custom Providers

createCustomProvider

const provider = await authpipe.createCustomProvider({
  id: "my-internal-api",
  name: "My Internal API",
  auth_api_key: { /* config */ },
});

getCustomProvider

const provider = await authpipe.getCustomProvider("my-internal-api");

updateCustomProvider

const provider = await authpipe.updateCustomProvider("my-internal-api", {
  name: "Updated Name",
});

deleteCustomProvider

await authpipe.deleteCustomProvider("my-internal-api");

Events

searchEvents

const resp = await authpipe.searchEvents({
  filter: { event_type: { eq: "connection.created" } },
  sort: [{ field: "created_at", direction: "desc" }],
  limit: 50,
});

API Keys

listApiKeys

const keys = await authpipe.listApiKeys();

createApiKey

const result = await authpipe.createApiKey("Production", "secret");
result.id   // API key ID
result.key  // Full key (only returned once)

revokeApiKey

await authpipe.revokeApiKey("key_abc123");

Webhook Config

getWebhookConfig

const config = await authpipe.getWebhookConfig();
config.webhook_url  // string
config.has_secret_1 // boolean
config.has_secret_2 // boolean

setWebhookConfig

const result = await authpipe.setWebhookConfig("https://yourapp.com/webhooks");
result.webhook_url // string
result.secret      // string (save this)

rotateWebhookSecret

const result = await authpipe.rotateWebhookSecret();
result.secret // new secret

deleteWebhookConfig

await authpipe.deleteWebhookConfig();

Workspaces

getWorkspace

const workspace = await authpipe.getWorkspace("ws_abc123");

updateWorkspace

const workspace = await authpipe.updateWorkspace("ws_abc123", {
  name: "New Name",
});

Error handling

import { AuthpipeApiError, AuthpipeError } from "@authpipe/node";

try {
  await authpipe.getCredential({ provider: "slack", tenantId: "org_acme" });
} catch (err) {
  if (err instanceof AuthpipeApiError) {
    console.log(err.statusCode); // HTTP status (e.g., 404)
    console.log(err.code);       // Error code (e.g., "not_found")
    console.log(err.message);    // Human-readable message
    console.log(err.requestId);  // X-Request-Id for support
  }
}

The SDK automatically retries on 429 (rate limit) and 5xx errors with exponential backoff (up to 3 attempts).

TypeScript types

All request and response types are exported from @authpipe/node:

import type {
  GetCredentialParams,
  GetCredentialResult,
  StoreCredentialParams,
  StoreCredentialResult,
  CreateAuthSessionParams,
  CreateAuthSessionResult,
  Connection,
  Installation,
  ProviderConfig,
  Provider,
  SearchRequest,
  SearchResponse,
} from "@authpipe/node";