Skip to main content
Hookfish sits between your application and OAuth providers. Your application refers to one linked account by a stable connection ID. Hookfish stores and refreshes the credentials behind that ID.

​
Core objects

A provider can have many connections. Reauthorizing the same connection ID for the same provider replaces its stored credentials. Reusing that ID for a different provider returns 409.

​
Connection lifecycle

1

Start authorization

Trusted code calls POST /api/oauth/authorize/{provider_path} with an explicit connection_id or a connection_id_prefix. Hookfish generates an ID when only a prefix is supplied.
2

Collect consent

Hookfish creates single-use state and returns an authorize_url. Your application redirects the user to that URL.
3

Complete the callback

The provider sends the browser to Hookfish. Hookfish claims the state, validates the provider response, exchanges the code, and encrypts the returned credentials.
4

Use the connection

Trusted server code calls GET /api/oauth/tokens/{connection_id}. Hookfish refreshes an expiring token when the provider supports refresh.
5

Disconnect

Hookfish requests upstream revocation when supported, then deletes the local connection.

​
Callback destinations

Set returnTo in hookfish.config.ts for a fixed post-callback destination. An authorization request can override it with return_to when that URL’s origin appears in trustedOrigins. Successful redirects include hookfish_status=connected, provider, and connection_id. Failed flows include hookfish_status=error and a stable error code. When no destination is configured, Hookfish renders a development completion page. Provider callbacks do not use a broker token. Their encrypted, single-use OAuth state authenticates the flow and expires after ten minutes. Runtime stats, Swagger UI, the OpenAPI document, and MCP client metadata are also public.

​
Application API and Hookfish API

Authenticate browser requests in your application. The authorized route handler can then use a typed Hono RPC client to call Hookfish with the correct scoped broker token. Keep provider-token retrieval, vault values, and broker administration inside trusted server code. Hookfish also includes an optional /api/client browser facade. It exposes an allowlist of connection-management operations, but it uses one configured broker credential and does not establish your application’s tenant boundary. Prefer an authenticated application route when serving your users.

​
Portable runtime and storage

HookfishServer.init(config) returns an object with a Fetch-compatible fetch handler. Framework adapters translate their request model or mount that handler without changing Hookfish’s API. Database adapters follow the same request-aware model:
  • PGlite persists to a local directory and applies bundled migrations lazily.
  • Postgres accepts a URL or a resolver that reads request bindings.
  • The experimental SQLite Durable Objects adapter selects a storage object from the validated organization context.
Continue with resource and provider scopes, or inspect all configuration options.