OAuth providers

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.

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:

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.

Do not construct callback URLs from forwarded host headers. Set OAUTH_REDIRECT_BASE_URL to the public HTTPS origin in production.

Select provider scopes

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

{
  "connection_id": "acme/engineering/github",
  "scopes": ["read:user", "repo"]
}

These are upstream permissions, not Hookfish resource 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, dynamic providers, or custom providers.

Get started

Store secrets

Integrate

Deploy

Secure and scale

Operate

Configure built-in providers

Register callback URLs

Select provider scopes

Choose a provider model

​Configure built-in providers

​Register callback URLs

​Select provider scopes

​Choose a provider model

Configure built-in providers

Register callback URLs

Select provider scopes

Choose a provider model