Configuration

Define shared broker behavior in hookfish.config.ts. Pass host-specific behavior as the second argument to HookfishServer.init.

Broker configuration

import { defineHookfishConfig } from '@hookfish/api'

export default defineHookfishConfig({
  db,
  providers,
  includeSwagger: true,
  returnTo: 'https://app.example.com/settings/integrations',
  trustedOrigins: ['https://app.example.com'],
  organizationRouting: false,
  providerManagement: false,
  onEvent: async (event) => auditLog.write(event),
})

Option	Type	Default	Purpose
`db`	`DatabaseInput`	Required	Ready, promised, or request-aware database
`providers`	Map, registry, source, or factory	Required	Resolve OAuth providers
`includeClient`	`boolean`	`false`	Mount the optional `/api/client` facade
`includeSwagger`	`boolean`	`true`	Include server-only routes in the OpenAPI document
`returnTo`	Absolute HTTP(S) URL	Development completion page	Fixed callback destination
`trustedOrigins`	URL array	`[]`	Allow per-flow returns and cross-origin browser calls
`organizationRouting`	`boolean`	`false`	Move management routes under an organization path
`providerManagement`	`boolean`	`false`	Enable dynamic-provider CRUD
`onEvent`	Event handler	Unset	Export best-effort lifecycle events

includeSwagger: false does not remove server routes. It filters the generated document to browser-safe operations and advertises /api/client as its server. For user-facing applications, keep includeClient at its default. Authenticate requests on your application API, then use a server-side Hono RPC client to call Hookfish with a scoped broker token.

Runtime options

import { HookfishServer } from '@hookfish/api'

const hookfish = await HookfishServer.init(config, {
  runtime: 'node',
})

Option	Purpose
`runtime`	Label returned by `/api/client/health`
`browserOrigins`	Override the config’s browser CORS allowlist
`brokerApiKey`	Resolve the credential injected by the browser facade
`authorizeBrowserRequest`	Apply application authentication and authorization

runtime, browserOrigins, and brokerApiKey can resolve values from the current runtime bindings. The last three options apply to the optional browser facade. They are not needed when your application authenticates users separately and calls Hookfish from trusted server routes.

Provider inputs

providers accepts:

A record of provider IDs to implementations
A ProviderRegistry
A lazy ProviderSource
A synchronous or asynchronous factory that returns one of those inputs for the current bindings

Use a factory for request-bound secrets. Use createProviderSource for a large application-owned catalog where resolving one provider should not materialize the complete list. See Environment variables and OAuth providers for concrete values.

HTTP API

Security

Configuration

Broker configuration

Runtime options

Provider inputs

​Broker configuration

​Runtime options

​Provider inputs

Broker configuration

Runtime options

Provider inputs