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

# OAuth providers

> Configure GitHub, Linear, Notion, MCP, and application-owned provider registries.

An OAuth provider owns one service's authorization URLs, provider scopes, token
exchange, refresh behavior, revocation, and public metadata. Hookfish resolves a
provider by its ID when an authorization or token operation runs.

## Configure built-in providers

`@hookfish/providers` exports provider factories for GitHub, Linear, Notion,
and remote MCP servers.

```ts theme={null}
import { defineHookfishConfig } from '@hookfish/api'
import {
  createGitHubProvider,
  createLinearProvider,
  createMcpProvider,
  createNotionProvider,
} from '@hookfish/providers'

export default defineHookfishConfig({
  db,
  providers: (env: typeof process.env) => ({
    github: createGitHubProvider({
      clientId: env.GITHUB_CLIENT_ID,
      clientSecret: env.GITHUB_CLIENT_SECRET,
    }),
    linear: createLinearProvider({
      clientId: env.LINEAR_CLIENT_ID,
      clientSecret: env.LINEAR_CLIENT_SECRET,
    }),
    mcp: createMcpProvider(),
    notion: createNotionProvider({
      clientId: env.NOTION_CLIENT_ID,
      clientSecret: env.NOTION_CLIENT_SECRET,
    }),
  }),
})
```

Provider factories run with the bindings passed to `hookfish.fetch`. This lets
a Worker read provider credentials from request bindings without capturing
stale values in its module scope.

## Register callback URLs

Ask the running broker for the exact callback URL for each provider:

```bash theme={null}
curl http://127.0.0.1:8787/api/oauth/providers \
  --header "Authorization: Bearer $HOOKFISH_API_KEY"
```

The response also reports whether each provider is configured, its default and
available provider scopes, and whether it supports refresh or revocation. Copy
the returned `callback_url` into the provider's developer console.

<Warning>
  Do not construct callback URLs from forwarded host headers. Set
  `OAUTH_REDIRECT_BASE_URL` to the public HTTPS origin in production.
</Warning>

## Select provider scopes

Pass `scopes` when starting an authorization to override the provider's
defaults for that connection.

```json theme={null}
{
  "connection_id": "acme/engineering/github",
  "scopes": ["read:user", "repo"]
}
```

These are upstream permissions, not Hookfish [resource scopes](/concepts/scopes).

## Choose a provider model

| Model                | Use it when                                                     |
| -------------------- | --------------------------------------------------------------- |
| Fixed provider map   | The deployment has a small, known set of OAuth applications     |
| Dynamic provider     | Operators or tenants create configurations at runtime           |
| Lazy provider source | An application-owned catalog contains many provider definitions |
| Custom provider      | A service's OAuth dialect is not included in Hookfish           |

Continue with [remote MCP providers](/providers/remote-mcp),
[dynamic providers](/providers/dynamic), or
[custom providers](/providers/custom).