OAuth Providers

A provider is trusted application code selected by the final segment of a connection path. Request bodies cannot choose a provider implementation or upload deployment credentials.

Use a trusted provider

Start with a built-in provider when Hookfish already supports the service. The provider owns credential acquisition and refresh. Your trusted application accesses the current credential and passes it to the service’s SDK.

Configure GitHub

import { defineHookfishConfig } from '@hookfish/api'
import { createGitHubProvider } from '@hookfish/providers'

export default defineHookfishConfig({
  db,
  providers: (env: typeof process.env) => ({
    github: createGitHubProvider({
      clientId: env.GITHUB_CLIENT_ID,
      clientSecret: env.GITHUB_CLIENT_SECRET,
    }),
  }),
})

Provider IDs must be non-reserved lower-camel JavaScript identifiers up to 128 characters. Slashes, hyphens, dots, and reserved words such as class are not allowed. Register this callback URL in the GitHub OAuth application:

https://broker.example.com/api/connections/callback/github

Set OAUTH_REDIRECT_BASE_URL to the public broker origin in production. Other fixed OAuth providers use the same callback pattern with their provider ID as the final segment.

Make a GitHub request with Octokit

Install the Hookfish SDK in the trusted application that uses the connection:

pnpm add @hookfish/sdk

Pass the GitHub connection path, then request the connected user with the authenticated Octokit client returned by Hookfish:

import { Hookfish } from '@hookfish/sdk'

const API_KEY = process.env.HOOKFISH_API_KEY
if (!API_KEY) throw new Error('HOOKFISH_API_KEY is required')

const hookfish = new Hookfish({
  apiKey: API_KEY,
  baseUrl: 'https://broker.example.com/api',
})

const github = await hookfish.github('user/personal/github')
const { data: user } = await github.rest.users.getAuthenticated()
console.log(`Connected as ${user.login}`)

The first access throws authorization_required when the connection needs consent. Open its authorizeUrl, complete GitHub authorization, and repeat the request. Hookfish keeps the provider token in trusted server code and injects it into Octokit. The same initializer is available as hookfish.provider.github({ connection }).

Authentication and provider inputs

GET /connections/providers describes credential acquisition and provider inputs. The authentication value is either oauth or secret. Each input field declares how Hookfish uses it:

identity adds a segment to the connection path.
configuration supplies immutable, non-secret connection configuration.
scopes requests provider scopes.

GitHub, Linear, and Notion use OAuth and expose optional scopes without connection-specific configuration. The generic mcp provider uses OAuth and requires a resource name and URL, with optional scopes. The generic secret provider requires a credential name and a supplied value. The mcp provider stores its URL as immutable connection configuration. Requested and granted provider scopes are tracked separately and can change only through the authorization lifecycle. Continue with remote MCP servers for the MCP client flow.

Implement a custom provider

Implement OAuthProvider from @hookfish/provider when Hookfish does not include the service. The provider owns the upstream protocol details. Hookfish owns state, storage, encryption, resource authorization, and connection lifecycle.

Required operations

Every OAuth provider must create an authorization request and exchange the returned code.

import type {
  CreateAuthorizationInput,
  ExchangeCodeInput,
  OAuthProvider,
  ProviderTokenResponse,
} from '@hookfish/provider'
import { ProviderRequestError } from '@hookfish/provider'

export class ExampleProvider implements OAuthProvider {
  readonly label = 'Example'
  readonly defaultScopes = ['profile.read']
  readonly availableScopes = ['profile.read', 'projects.read']

  constructor(
    private readonly clientId: string,
    private readonly clientSecret: string,
  ) {}

  createAuthorization(input: CreateAuthorizationInput) {
    const url = new URL('https://accounts.example.com/oauth/authorize')
    url.searchParams.set('response_type', 'code')
    url.searchParams.set('client_id', this.clientId)
    url.searchParams.set('redirect_uri', input.redirectUri)
    url.searchParams.set('state', input.state)
    url.searchParams.set('scope', input.scopes.join(' '))
    return { url: url.toString() }
  }

  async exchangeCode(
    input: ExchangeCodeInput,
  ): Promise<ProviderTokenResponse> {
    const response = await fetch('https://accounts.example.com/oauth/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        grant_type: 'authorization_code',
        code: input.code,
        redirect_uri: input.redirectUri,
        client_id: this.clientId,
        client_secret: this.clientSecret,
      }),
    })
    const payload: unknown = await response.json()
    if (
      !response.ok ||
      typeof payload !== 'object' ||
      payload === null ||
      Array.isArray(payload) ||
      typeof Reflect.get(payload, 'access_token') !== 'string'
    ) {
      throw new ProviderRequestError('Example token exchange failed.')
    }

    return { payload: Object.fromEntries(Object.entries(payload)) }
  }
}

Keep client authentication, request encoding, response validation, PKCE generation, and error translation inside the provider package.

Optional capabilities

Implement refreshToken when the provider issues refresh tokens. Implement revokeToken when it exposes a revocation API. Hookfish reports these capabilities in provider discovery and invokes them at the appropriate point in the connection lifecycle. Implement isConfigured when provider availability depends on deployment credentials. Register the instance under a trusted provider ID in hookfish.config.ts. OAuthProviderTemplate is reserved for trusted implementations such as mcp that need connection-owned configuration. A lazy ProviderSource remains available for large application-owned catalogs.

Validate every upstream JSON response before returning it. Throw ProviderConfigurationError for invalid local configuration and ProviderRequestError for upstream failures.

Get started

Store secrets

Integrate

Deploy

Secure and scale

Operate

Use a trusted provider

Configure GitHub

Make a GitHub request with Octokit

Authentication and provider inputs

Implement a custom provider

Required operations

Optional capabilities

​Use a trusted provider

​Configure GitHub

​Make a GitHub request with Octokit

​Authentication and provider inputs

​Implement a custom provider

​Required operations

​Optional capabilities

Use a trusted provider

Configure GitHub

Make a GitHub request with Octokit

Authentication and provider inputs

Implement a custom provider

Required operations

Optional capabilities