Connectors

How the current provider catalog, authentication methods, and toolkits fit together.

Open Connector separates authentication providers from toolkits. This matters: a provider defines how credentials are collected, stored, refreshed, and injected; a toolkit defines the executable tools an agent can call. They often share a slug, but neither is a synonym for the other.

The current catalog model

Catalog object	Owns	Runtime representation
Authentication provider	OAuth/API-key/basic methods, connection fields, outbound proxy rules, credential verification, and provider metadata.	A `ProviderConfig` is validated and seeded into `provider_config`.
Toolkit	Agent-facing tool metadata and executable operations. A toolkit can refer to an auth provider, a different auth provider, or no auth provider yet.	Registry and official toolkit artifacts are published to the toolkit catalog.
Connection	One user's encrypted credential set for one selected provider authentication method and project scope.	Stored separately from both catalog objects.

The runtime catalog is not limited to GitHub and Telegram. It contains a generated provider catalog plus official and generated toolkits. Use the authenticated toolkit discovery endpoint or the live API reference to see the deployment you are calling.

The old flattened connector shape—one top-level authMode, authorizationUrl, tokenUrl, and credentials—is obsolete. Authentication is now an authMethods array, so one provider can offer OAuth and personal-token flows side by side.

Authentication methods

Each entry in authMethods has a namespaced id such as github.oauth2 and is either available or explicitly unavailable with a reason. Available methods use one of these kinds:

Kind	What the user supplies	What the broker does
`oauth2`	Browser consent, or client credentials when configured.	Builds the authorization URL, exchanges and refreshes tokens, then stores them encrypted.
`api_key`	A long-lived key or token.	Encrypts the supplied fields and injects them into the configured request.
`basic`	Username/password or equivalent key/secret pair.	Encrypts both values and injects basic-auth credentials or configured request fields.

An unavailable method remains visible to describe catalog coverage, but cannot be used until its required runtime adapter is implemented.

Provider configuration

ProviderConfig remains the internal type for an authentication provider; its current shape is below. The required fields are slug, displayName, authMethods, and proxy.baseUrl.

Field	Purpose
`authMethods`	One or more named methods. OAuth options belong under `method.oauth2`; API-key/basic fields belong under `method.credentials`.
`connectionConfig`	Non-default per-connection fields, such as a tenant hostname or account ID. Sensitive fields can be marked `secret`.
`proxy`	Provider-wide base URL, allowlist, request templates, and optional credential verification request. A method may add its own header/query/body templates.
`description`, `logoDomain`, `appUrl`, `authGuideUrl`, `documentationUrl`	Catalog metadata shown to users and agents.
`version`, `deprecated`, `categories`, `changelog`	Lifecycle and discovery metadata.

OAuth provider example

import type { ProviderConfig } from "@open-connector/catalog";

export const myCrm = {
  slug: "my-crm",
  displayName: "My CRM",
  authMethods: [
    {
      id: "my-crm.oauth2",
      displayName: "My CRM OAuth",
      kind: "oauth2",
      status: "available",
      oauth2: {
        authorizationUrl: "https://app.mycrm.com/oauth/authorize",
        tokenUrl: "https://app.mycrm.com/oauth/token",
        defaultScopes: ["contacts:read", "contacts:write"],
        scopeSeparator: " ",
      },
    },
  ],
  proxy: {
    baseUrl: "https://api.mycrm.com/v2",
    headers: { authorization: "Bearer ${accessToken}" },
  },
  documentationUrl: "https://developers.mycrm.com/api",
  categories: ["crm"],
} satisfies ProviderConfig;

API-key provider example

Credential fields are nested under the method, not at the provider root. Method-level templates let different methods inject their credentials differently while sharing the same provider base URL.

export const myApi = {
  slug: "my-api",
  displayName: "My API",
  authMethods: [
    {
      id: "my-api.api_key",
      displayName: "API key",
      kind: "api_key",
      status: "available",
      credentials: {
        apiKey: {
          type: "string",
          title: "API key",
          description: "Key from account settings",
          secret: true,
        },
      },
      proxy: { headers: { authorization: "Bearer ${apiKey}" } },
    },
  ],
  proxy: {
    baseUrl: "https://api.example.com/v1",
    verification: { method: "GET", endpoints: ["/me"] },
  },
} satisfies ProviderConfig;

Working with the deployed catalog

Create and maintain provider catalog entries as source-controlled catalog data; server startup validates and idempotently seeds authentication providers. Toolkits are maintained as registry artifacts and published independently. Do not create a toolkit merely to model authentication, and do not assume a provider automatically provides executable tools.

For an agent or integration, the normal sequence is:

Discover the toolkit and its supported authentication methods.
Create or choose an auth configuration for the selected method.
Create a connection for the user and project scope.
Invoke a tool through that connection.

See API reference for the exact deployed discovery and execution routes, and Connected accounts for the credential lifecycle.