> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hookfish.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Reference Hookfish config fields and runtime-specific options.

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

## Broker configuration

```ts theme={null}
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

```ts theme={null}
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](/reference/environment) and
[OAuth providers](/authentication/oauth-providers) for concrete values.