> ## 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.

# How Hookfish works

> Understand Hookfish connections, request surfaces, callbacks, and credential boundaries.

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

| Object                | Meaning                                                        |
| --------------------- | -------------------------------------------------------------- |
| OAuth provider        | Protocol implementation and client configuration for a service |
| Connection            | One authorized provider account identified by a resource path  |
| Broker access token   | Credential used to call Hookfish                               |
| Provider access token | Upstream credential returned only to trusted server code       |
| Vault secret          | Non-OAuth credential encrypted under a resource path           |

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Collect consent">
    Hookfish creates single-use state and returns an `authorize_url`. Your
    application redirects the user to that URL.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Use the connection">
    Trusted server code calls `GET /api/oauth/tokens/{connection_id}`. Hookfish
    refreshes an expiring token when the provider supports refresh.
  </Step>

  <Step title="Disconnect">
    Hookfish requests upstream revocation when supported, then deletes the
    local connection.
  </Step>
</Steps>

## 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

| Surface              | Purpose                           | Authentication                            |
| -------------------- | --------------------------------- | ----------------------------------------- |
| Your application API | User-facing connection operations | Your application session and permissions  |
| Hookfish `/api/*`    | Complete broker API               | Root or scoped broker credential          |
| `/api/docs`          | Swagger UI                        | Visibility controlled by `includeSwagger` |
| `/api/openapi.json`  | OpenAPI 3.1 document              | Visibility controlled by `includeSwagger` |

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](/concepts/scopes), or inspect all
[configuration options](/reference/configuration).