API providers: the registry and the catalog

An API provider is an API the Gateway holds a key for and brokers calls to (DataForSEO, Context.dev, Stripe): an app lists it under capabilities in everyapp.config.ts and calls the provider's real URLs with integrationFetch(), and the Gateway puts the key on the call, so no app ever holds it. An MCP app (pnpm everyapp mcp on dataforseo, /docs/agent/mcp) is something else: an app of the Gateway's own with no page, whose tools members' AI clients call on /mcp. An MCP app is built on an API provider's entry (DataForSEO's tools call DataForSEO through the same proxy), and nothing on this page changes MCP apps. The design and its decisions are in the repository's docs/design/2026-10-provider-registry.md.

The catalog and a Gateway's rows

Every provider the Gateway knows comes from one of two places, resolved as one lookup, the registry (providerRegistry() in packages/sdk/src/internal/providerRegistry.ts):

The catalog comes first and a row can never shadow it, so nothing a row says changes where a catalog provider's key goes. A row is the Gateway's, not an organization's: its key is one Gateway setting shared by every app and every organization on that Gateway, as a catalog provider's is. A Gateway whose D1 predates migration 0013, or whose rows can't be read, serves the catalog alone (logged provider.rows_unavailable, once per isolate).

The catalog has four kinds (mode in the code). Only the first is a spec a Gateway can register:

An AI provider under capabilities is refused at deploy (capabilities.openrouter: openrouter is an AI provider: list it under providers, not capabilities), and /api/integrations/openrouter/… answers 400 invalid_integration_route.

How an app lists one

Nothing in the manifest is new. A registered provider is listed like a catalog one, with the need fields of the manifest page:

capabilities: {
  stripe: { access: "read", why: "Shows the last ten charges on the dashboard." },
},

access: "write" takes effect only on a provider whose spec offers write: it unlocks the spec's writeMethods, and a call under an agent's identity (chan: "mcp") still needs the mcp:write scope for them (integration_read_only). The app calls it with integrationFetch({ env, provider: "stripe", for: request }): an id outside the catalog is accepted, sent over the EVERY_APP_GATEWAY binding with only an https check, and the Gateway's checks decide.

everyapp deploy checks the manifest against the Gateway's registry once connected, so a registered provider's entry is checked like a catalog one (the access it offers, no scope sets), and an id neither the catalog nor the rows have is CAPABILITY_UNKNOWN, whose fix is pnpm everyapp provider add <spec>. An app's secrets may not name a row's setting either (the validator's wording for a Gateway name). everyapp dev can't ask the Gateway: it accepts an id outside the catalog and warns CAPABILITY_NOT_IN_CATALOG for each (local development).

The spec

One JSON object, the same shape every catalog entry has in TypeScript (parseProviderSpec in packages/sdk/src/internal/providerSpec.ts parses it; providerSpecOf writes a catalog entry back as one):

{
  "id": "stripe",
  "name": "Stripe",
  "description": "Payments: customers, subscriptions, invoices.",
  "docs": "https://dashboard.stripe.com/apikeys",
  "api": "https://docs.stripe.com/api",
  "hosts": ["api.stripe.com"],
  "auth": { "kind": "bearer", "secret": "STRIPE_API_KEY" },
  "secrets": [
    {
      "name": "STRIPE_API_KEY",
      "hint": "A restricted key with read access to Customers and Charges is enough."
    }
  ],
  "access": ["read", "write"],
  "readMethods": ["GET", "HEAD"],
  "writeMethods": ["POST", "PUT", "PATCH", "DELETE"],
  "accountWidePaths": [
    ["v1", "account"],
    ["v1", "api_keys"]
  ],
  "data": "account",
  "hint": "A restricted key from the Stripe dashboard; the Gateway puts it on every call as a bearer token.",
  "smoke": {
    "method": "GET",
    "path": "/v1/balance",
    "expect": [200],
    "free": true
  },
  "cost": {
    "unit": "call",
    "usd": 0,
    "note": "Free; Stripe charges per transaction, not per call."
  },
  "rate": { "perSecond": 100, "note": "Live mode; test mode 25/s." },
  "example": "list my latest Stripe customers",
  "verified": { "on": "2026-10-25", "how": "docs" },
  "tags": ["payments"]
}

A spec names Gateway settings and never holds a value: no field takes one. Every field, with the parser's rule; any other field, anywhere in the object, is unknown field, and no text may hold a control character:

Setting names (auth.secret, auth.user.secret, hostSetting, secrets[].name) match ^[A-Z][A-Z0-9_]{2,63}$. The parser reports every problem at once, each with its path, joined in the order of the table above as PROVIDER_SPEC_INVALID's message: hosts.0: must be a bare lowercase host with a dot and no port, path or scheme (api.stripe.com); auth.secret: must name a Gateway setting: upper case letters, digits and underscores, a letter first, 3 to 64 characters (STRIPE_API_KEY).

Auth kinds: the request each makes

secret is always the name of a Gateway setting; the value is read from the Gateway's settings at the call, trimmed. While a setting auth names is unset or blank, calls answer 503 integration_not_configured.

as is required for basic and says where the key goes, never guessed from the value; user belongs to as: "password" only. The fifth kind, oauth2-user, is an OAuth provider the Gateway runs the user flow for (below); its auth names the two client settings instead of a secret. Any other kind is refused: an AI provider is a catalog entry; a client-credentials exchange and signed requests (AWS SigV4, HMAC) aren't in this slice. A fixed header the provider wants on every call (anthropic-version, Notion-Version) is the app's to send: the Gateway forwards an app's ordinary headers. Every request also loses the app's Authorization, x-api-key, cookies, x-everyapp-* and forwarding headers before the key goes on, and is made with redirect: "manual".

hostSetting: a host of the operator's

For a provider whose host is per account (Shopify's <shop>.myshopify.com), the spec names hostSetting, a Gateway setting under the provider's prefix like its key (SHOPIFY_HOST), instead of or beside hosts. Its value is a bare host or an https origin with nothing else (no path, port, query or userinfo), and the key may go to that host as well as hosts; without a value the provider has no host there and the call is 400 invalid_integration_route. The value's shape is checked when read (hostSettingValue in packages/sdk/src/internal/capabilities.ts); the operator who sets it decides the host.

data: whose data the key reaches

"per-call": each call is its own (search, scrape, inference, weather). "account": every list is the whole account the key belongs to (Stripe, Airtable, Linear). One key is every organization's on a Gateway, so a hosted Gateway refuses an account provider (503 integration_not_available_hosted) until it holds per-organization keys; a self-hosted Gateway, one organization, serves it.

What a row may say

Registering a provider gives the Gateway a new host to send a key to. These rules keep that from sending any other key anywhere, run by provider add before it writes and by the Gateway every time it reads a row (checkProviderRow and providerRegistry in packages/sdk/src/internal/providerRegistry.ts); each is a row of the threat model's register (B4):

The other direction holds too: an app whose secrets names a row's setting is refused at deploy, as for any Gateway setting.

The key is bound to the hosts it was set for

A registered provider's setting is a Gateway setting like any other, set with pnpm everyapp secret set STRIPE_API_KEY from any directory. It isn't in SETTABLE_GATEWAY_SETTINGS (that list is the catalog's), so secret set connects first and asks the rows which provider holds the name. Before it asks for the value it prints whose it is and where it will go:

STRIPE_API_KEY is Stripe's, registered by ops@example.com on 2026-10-25; the key is sent to api.stripe.com.

After the value is set it records on the row what the key was set for: providerBindingKey of the row (its hosts, hostSetting and auth as one canonical string) in bound_to, with bound_at. The Gateway reads the key for a row only while that still matches the row it has. So:

• A row added and never given a key is not set up: calls answer 503 integration_not_configured, its status configured: false, and every app that lists it shows "Needs setup" (its setting reads as unset in status, secret list and the Gateway's app lists), even when the name happens to be set on the Gateway Worker.
• A row replaced (provider add --replace), removed and added again, or edited by hand in D1 is unbound until secret set runs again: calls answer 503 integration_not_configured with <Name>'s key was set for other hosts than the provider has now. Its operator sets it again with: everyapp secret set <NAMES>. A person changing a row's hosts sets the key again; nobody who can only rewrite rows can move a key the operator set.
• provider remove leaves the setting on the Gateway Worker (pnpm everyapp secret unset STRIPE_API_KEY removes it), and nothing reads it until a new row is bound by a new secret set.

OAuth providers: upload a client, the Gateway runs the flow

An OAuth provider is a provider whose credential is a person's: GitHub, Google, Notion, Linear, any API with an OAuth 2 authorization-code flow. Since 2026-10-25 it is a kind of the registry (docs/design/2026-10-oauth-providers.md): an owner or admin adds one from a preset or a spec, pastes the client id and secret the provider issued, and the Gateway runs the whole flow itself, holds each person's tokens sealed, refreshes them, and puts the right token on every call an app makes through integrationFetch(). The app never sees the client secret, the access token or the refresh token; it sees calls that go through and refusals that say what to do.

Two flows exist on the same client, and a catalog entry may offer both (integrationStatus().flow is app, gateway or both):

• The app-driven flow (app): the social networks' entries since #326. The app builds the authorize URL from the status's clientId, receives the callback on its own host, exchanges the code through the Gateway's token-endpoint proxy and keeps the person's tokens itself. Unchanged.
• The Gateway-owned flow (gateway, this section): the person connects once, in the Gateway, and every app that lists the provider calls it through the proxy with that connection. google-workspace, microsoft-365, slack and discord offer both; every registered OAuth provider and every preset offers this one.

The spec: auth.kind: "oauth2-user"

The same JSON a row of any kind is, with auth an OAuth block and a scopeSets object; parseProviderSpec takes it, and oauthSpecOf writes a catalog entry that has a flow back as one (provider show <id> prints it):

{
  "id": "github-oauth",
  "name": "GitHub",
  "description": "Repositories, issues, pull requests and the person's profile.",
  "docs": "https://github.com/settings/developers",
  "api": "https://docs.github.com/rest",
  "hosts": ["api.github.com"],
  "auth": {
    "kind": "oauth2-user",
    "authorizeUrl": "https://github.com/login/oauth/authorize",
    "tokenUrl": "https://github.com/login/oauth/access_token",
    "revokeUrl": "https://api.github.com/applications/{client_id}/grant",
    "revokeMethod": "DELETE",
    "clientId": "GITHUB_OAUTH_CLIENT_ID",
    "clientSecret": "GITHUB_OAUTH_CLIENT_SECRET",
    "inject": "form",
    "pkce": true,
    "scopeDialect": "comma",
    "tokenHeaders": { "Accept": "application/json" },
    "identity": {
      "url": "https://api.github.com/user",
      "label": "login",
      "id": "id"
    }
  },
  "scopeSets": {
    "identity": {
      "label": "GitHub account (who you are)",
      "access": "read",
      "scopes": ["read:user", "user:email"]
    },
    "repo.read": {
      "label": "Repositories (read, private ones included)",
      "access": "read",
      "scopes": ["repo"]
    },
    "repo.write": {
      "label": "Repositories (read and write)",
      "access": "write",
      "scopes": ["repo"]
    },
    "org.read": {
      "label": "Organizations and teams (read)",
      "access": "read",
      "scopes": ["read:org"]
    }
  },
  "access": ["read", "write"],
  "hint": "Register an OAuth App (not a GitHub App) and paste its client id and secret."
}

The common fields (id, name, description, docs, api, hosts, access, readMethods, writeMethods, hint, example, tags) follow the table above; docs is where the person makes the OAuth app (the console). hosts are the API hosts the person's token is sent to; the authorize, token and revoke hosts need not be among them. The OAuth fields, with the parser's rule; any other field under auth is not a field of auth.kind oauth2-user:

A set with routes unlocks those paths only (GET and HEAD on paths, the posts patterns); a set without routes unlocks every path on hosts for its access (a read set the readMethods, a write set the write methods too). On every host the segments batch and $batch never pass. The parsed spec is the same OAuthClientCapability a catalog client is, with a scopePolicy built from the sets (grantTypes authorization_code and refresh_token, requestScope: "keep") and a flow block carrying the rest; isOAuthProvider() is true for it.

The row rules of the table above hold with the client settings in place of the key, and one more: oauth.client-bound-to-endpoints. A client uploaded for a row stays usable only while the row still has the authorize, token and revoke URLs, hosts, inject and setting names it was uploaded for (providerBindingKey over those); a row replaced since reads as having no client until the client is pasted or set again, and the token-endpoint branch and the status refuse an unbound OAuth row too.

Presets

OAUTH_PRESETS (packages/sdk/src/internal/oauthPresets.ts) are specs of this shape shipped with the SDK, one per provider: github-oauth, notion-oauth, linear-oauth, gitlab-oauth, atlassian (Jira and Confluence), hubspot-oauth, zoom, dropbox, spotify and x-oauth (X's OAuth 2 with PKCE; X's OAuth 1.0a stays an app secret). An id carries -oauth where the catalog already holds an API-key entry of that name, so github (a token) and github-oauth (a person's grant) are two providers with two setting families. A preset becomes a row when added (provider add --oauth github-oauth, the dialog, everyapp_provider_add with { preset }), so provider show github-oauth prints it and a copy can be edited and added again under another id; a preset is a starting point, never a hidden catalog entry. Each is parsed by a test, and the catalog table below lists them with the catalog's clients. The catalog's own OAuth entries that have a flow, google-workspace, microsoft-365, slack and discord, are offered in the same picker, marked built in: adding one uploads the client only and writes no row.

The client: pasted in the Gateway, or set from a terminal

One client per provider per Gateway, as a row's key is. Two places can hold it, and the first that is set wins:

1. Worker secrets, set from a terminal: pnpm everyapp secret set GITHUB_OAUTH_CLIENT_ID GITHUB_OAUTH_CLIENT_SECRET (the row's two settings; GOOGLE_WORKSPACE_CLIENT_ID and its secret for the catalog's Google), which binds the row as any key does. The CLI never writes the sealed copy: the key that seals it lives in the Worker.
2. The oauth_clients table, pasted in Manage workspace → Providers (the Add OAuth provider dialog, or Replace client): the client id in clear, the secret sealed (AES-256-GCM through WebCrypto, a random nonce per value, stored as v1.<nonce>.<ciphertext>; the key derived once per isolate with HKDF-SHA256 from BETTER_AUTH_SECRET with the info everyapp:oauth:v1, so no new setting is needed; apps/every-app-gateway/src/server/secrets/sealed.ts), with who pasted it and when, and the row's binding key. A sealed value that no longer opens (the secret rotated) reads as no client.

provider list, provider show, the Admin table and everyapp_provider_list say which source is live (env or d1, the client id, who, when) and never a secret. Forget pasted client in the dialog deletes the sealed copy (its twin from a terminal is secret unset of the two settings); Replace client overwrites it. The redirect URI the person registers at the provider's console is https://<gateway>/connect/<id>/callback; every surface prints it beside the console's URL.

The flow

GET /connect/<id>?account=user|organization&return=<path or app URL>&sets=a,b
  the person's own session (any member for `user`; an owner or admin for `organization`,
  the workspace's one account background work uses); the provider must be an OAuth
  provider with a live client (404 or 409 saying why)
  sets: the ones named, else the union of the sets every active app that lists the
  provider declares, else every set the provider has; `identity` always when it exists
  → one `oauth_states` row (32 random bytes as the state, the PKCE verifier, who, which
    organization, the account kind, the sets, where to return; 10 minutes, one use)
  → 302 to authorizeUrl with response_type=code, client_id, redirect_uri, scope (the
    union, in the dialect's separator), state, code_challenge(_method=S256), authorizeParams

GET /connect/<id>/callback?code&state            ← the redirect URI
  the state row is this person's, unexpired, and deleted at once (`oauth.state-single-use`)
  an `error` from the provider ends on a Gateway page, never a redirect
  → POST tokenUrl with code, redirect_uri, code_verifier, the client as `inject` says,
    tokenHeaders; 64 KiB answer, redirect: "manual", never logged
  → the granted scopes (the dialect) must cover the sets asked; an excess beyond
    `tolerated` is refused and the tokens dropped (the scopes design's rules)
  → `identity` names the account; one `provider_connections` row per
    (organization, provider, subject), replaced on reconnect, tokens sealed
  → `provider.connected` with the actor
  → 302 to `return`: a path on the Gateway, or an https URL whose host is one of this
    Gateway's app hosts (APP_BASE_DOMAIN, a registered app's host; http://localhost:<port>
    in GATEWAY_DEPLOYMENT_MODE=dev). Anything else lands on Settings → Connected accounts

An app sends people into it with connectUrl({ env, provider, returnTo, account }) (@every-app/sdk/server: <GATEWAY_URL>/connect/<id>?return=…&account=…; connectPath is the path alone, also on the status). The person lands back where they were, connected.

Refresh. A call through the proxy refreshes a connection whose expires_at is within 60 seconds, under a lease on the row (one conditional UPDATE, so parallel calls don't race); a refresh the provider refuses marks the connection expired, emits provider.connection_expired once, and calls answer integration_not_connected with reconnect: true until the person connects again.

Disconnect. Settings → Connected accounts (own), Manage workspace → Providers (any), pnpm everyapp provider disconnect, everyapp_provider_disconnect: deletes the row, emits provider.disconnected, and revokes at the provider only when the spec has a revokeUrl. The Google entry has none on purpose: Google's revocation is per person per client and would also kill the tokens an app-driven app holds under the same client; the copy the Gateway drops dies at its expiry. GitHub, GitLab, Dropbox and Zoom revoke. The CLI's disconnect deletes without revoking (it has no token to revoke with) and says so.

Calls with the held token

/api/integrations/<id>/<host>/<path> for an OAuth provider, in this order:

1. The host is one of the provider's token endpoints: the app-driven branch, unchanged (OAuth clients).
2. The host is in hosts: the held-token branch. The app is active and lists the provider (capability_not_requested); the method is allowed (integration_method_not_allowed: read methods on any grant, write methods on access: "write" for a provider that offers it); the client is live (integration_not_configured); the call is attributed (admit()), and an agent's read-only connection may not write (integration_read_only); the connection: x-everyapp-account (integrationFetch's account; user when a person is behind the call, organization for background work) picks whose, and a missing or expired one is 409 integration_not_connected with { connectPath, reconnect }; the app's declared scopes must be within the connection's sets, else integration_not_connected with reconnect: true and the missing sets; the path must be covered by a declared set (403 integration_scope_not_allowed; heldTokenCallAllowed() in packages/sdk/src/internal/oauthScopes.ts); then the token is refreshed if due and put on the call as Authorization: Bearer, the app's Authorization, cookies, X-HTTP-Method-Override and any access_token or token query key are stripped, the call is made with redirect: "manual", set-cookie is dropped from the answer, the call is counted (Usage) and logged as integration.proxy.call with the set names.
3. Any other host: invalid_integration_route.

GET /api/integrations/<id> (the status) gains flow (app, gateway or both), connectPath, and for the caller's account connection: { account, label, scopeSets, ready, reconnect? } or null. An app shows "Connect GitHub" (a link to connectUrl()) on connection: null, "Reconnect" on reconnect: true, and calls on ready.

Scopes. As the scopes design says: a provider carries sets; an app declares the sets it needs under scopes (capabilities: { "github-oauth": { access: "read", scopes: ["identity", "repo.read"], why } }); the strict validator refuses an unknown set name for a provider that has sets and scopes on one that has none; the consent asks the union; the proxy holds the call to the declared sets. The catalog's Google and Microsoft sets are untouched: a Gateway-owned Google connection for OpenSEO asks identity, search-console.read and analytics.read, the same strings as the app-driven flow.

Who may do what

Adding, replacing a client, removing a provider, listing every connection and disconnecting someone else's account: owners and admins. Connecting and disconnecting one's own account: any member. The organization's account (account=organization): owners and admins. Rows are written by the Cloudflare login or by owners and admins through the dialog and everyapp_provider_add on a self-hosted Gateway (providers.add-is-privileged); the client is pasted by owners and admins in the dialog, or set by the login from a terminal; no tool argument ever carries a secret.

Events

provider.added and provider.removed (with provider.kind api_key or oauth), provider.updated (a client replaced, a spec replaced), provider.connected, provider.disconnected and provider.connection_expired, each with the actor and the account's kind and label, never a token (events). Held-token calls count in Usage like every proxied call; Activity stays the tools audit.

The commands

pnpm everyapp provider add stripe.json        # or an https URL; prints the hosts and the secret set to run
pnpm everyapp secret set STRIPE_API_KEY       # names the provider and its hosts, then binds the row
pnpm everyapp provider list                   # the catalog and the rows: settings set and bound, the apps listing each
pnpm everyapp provider show stripe            # the whole spec as JSON, for an agent to call it
pnpm everyapp provider remove stripe          # refuses while an active app lists it
pnpm everyapp provider presets                # the OAuth presets: GitHub, Notion, Linear, … and the built-in clients
pnpm everyapp provider add --oauth github-oauth   # registers GitHub; prints the redirect URI and the secret set to run
pnpm everyapp provider connections            # who connected what; never a token
pnpm everyapp provider disconnect github-oauth --user ben@example.com

From an AI client, the same registry is five built-ins on the Gateway connector: everyapp_provider_list for every member (with the OAuth presets), everyapp_provider_add (the spec object or { preset }, never a URL, never a replace), everyapp_provider_remove (refuses a bound or listed row), everyapp_provider_connections and everyapp_provider_disconnect (a member's own account; the organization's for owners and admins) for owners and admins on a self-hosted Gateway; see the provider tools. A key is never set through a tool.

All of them run from any directory under the Cloudflare login (as every Gateway command: --gateway, --account-id, --json, --verbose). A Gateway from before migration 0013 has no providers table: add and remove refuse and name pnpm everyapp update; list and show read it as having no rows.

provider add takes --oauth for an OAuth preset, built-in client or spec, --client-id for the client id (its secret on stdin as NAME=value, or --from-env), and --replace as for any row. source is catalog or row; addedBy is the Cloudflare login's email (or api-token:<account id>), addedAt epoch milliseconds. For an OAuth provider list and show add kind: "oauth", flow, redirectUri, client (source env, d1 or null, the client id, who, when) and the connections count. Nothing any of them prints or returns is a value: settings appear by name and set or not, a client by its id.

everyapp provider was the name of everyapp mcp until 2026-10-24. Through launch week, pnpm everyapp provider on <id> and pnpm everyapp provider off <id> stay as hidden routes that run mcp on|off and first print everyapp provider on is now everyapp mcp on; this alias goes after launch week.; provider list is this page's. The MCP apps' own codes, PROVIDER_APP_UNKNOWN and PROVIDER_KEY_UNSET, are unchanged.

Codes

What each means; the fix for a CLI code is in its data.fix and on the error codes page.

The Gateway's refusals carry their code in x-everyapp-error, so gatewayRefusal() tells them from the provider's own errors.

An OAuth provider with a Gateway-owned flow (flow: "both" in its status) is connected on the Gateway host: GET /connect/<id>?account=user|organization&return=<path or app URL>&sets=a,b starts the provider's authorize flow for the signed-in member (PKCE S256, a one-use state, ten minutes), and GET /connect/<id>/callback is the redirect URI the operator registers at the provider's console (everyapp provider show <id> prints it). The connection's tokens are sealed in the Gateway's database; an app's integrationFetch() to one of the provider's api hosts carries the person's token (or the organization's, with account: "organization", which background work uses), and the app never sees it. In the Gateway's logs, provider.row_invalid names a row it left out (provider, reason the refusal code, message), once per isolate.

OAuth providers

An OAuth provider is one people connect their own account to (the design is docs/design/2026-10-oauth-providers.md); provider add takes one with --oauth: the Gateway runs the authorize flow at /connect/<id> (PKCE and state), keeps each person's (or the organization's) tokens sealed in its D1, refreshes them, and puts the access token on the app's calls through the same proxy as an API key; the app never sees the token, the refresh token or the client secret. The row's spec is the shape above with auth.kind: "oauth2-user" (authorizeUrl, tokenUrl, revokeUrl?, clientId and clientSecret as setting names, inject, pkce, scopeDialect, authorizeParams?, tokenHeaders?, identity?) and scopeSets (named bundles an app lists under scopes). The SDK ships presets of that shape (OAUTH_PRESETS: github-oauth, notion-oauth, linear-oauth, gitlab-oauth, atlassian, hubspot-oauth, zoom, dropbox, spotify, x-oauth), and the catalog's google-workspace, slack, microsoft-365 and discord clients run the same flow.

pnpm everyapp provider presets                       # the presets and built-in clients, each with its scope sets and console
pnpm everyapp provider add --oauth github-oauth      # the row, then the redirect URI to register at github.com/settings/developers
pnpm everyapp secret set GITHUB_OAUTH_CLIENT_ID GITHUB_OAUTH_CLIENT_SECRET   # the client, from the terminal (binds the row)
# or in one run, the values never on the command line:
printf 'GITHUB_OAUTH_CLIENT_SECRET=%s\n' "$SECRET" | pnpm everyapp provider add --oauth github-oauth --client-id Iv1.abc --json
pnpm everyapp provider add --oauth google-workspace  # a built-in client: no row, its client alone
pnpm everyapp provider add --oauth ./acme.json       # a custom provider by its spec

The client is a Worker secret the CLI sets (<ID>_CLIENT_ID, <ID>_CLIENT_SECRET, bound to the row's endpoints like a key to its hosts), or one pasted under Admin → Providers, which the Gateway seals in D1; a Worker secret of the same name wins, so the operator can always rotate from the terminal. provider show <id> and provider list say which is live (client.source), the redirect URI, the flow (app: the app runs the flow itself, as the social networks do; both: the Gateway runs its connect flow and still completes an app's own token calls) and how many accounts are connected. People connect at <gateway>/connect/<id> (Settings → Connected accounts, a Connect button in Admin, or an app's link from connectUrl()); provider connections lists them and provider disconnect removes one. The CLI never holds a token: disconnect deletes the row and names the console to revoke the grant at, while Admin → Providers → Disconnect revokes it from the Gateway where the preset names a revoke URL (never at Google, whose revoke is per person per client). Events: provider.added and provider.removed carry provider.kind (api_key or oauth); provider.connected, provider.disconnected and provider.connection_expired carry the account and the scope sets, never a token.

An app lists the provider as any other, with the sets it needs: capabilities: { "github-oauth": { access: "read", scopes: ["identity", "repo.read"], why } }, and calls integrationFetch({ env, provider: "github-oauth", account?: "user" | "organization" }) with the provider's own URLs; a call with no connection for the account answers 409 integration_not_connected with connectPath, and one outside the connection's sets answers it with reconnect: true.

Local development

everyapp dev has no Gateway. For a catalog provider the SDK calls the provider directly with the developer's own key from .dev.vars, under the Gateway's setting name, by the same spec. For a registered provider it needs the spec too: everyAppWorker() reads .everyapp/providers/*.json in the app's directory into EVERYAPP_DEV_PROVIDERS (a JSON array of the specs), and integrationFetch() resolves the id from it and puts the key from .dev.vars (under the spec's setting names) where the spec's auth says. The file is what pnpm everyapp provider show <id> --save writes, or provider add run in the app's directory; a spec holds no value, so the file is safe to commit. Without a file the call throws a ConfigurationError that names the command, and everyapp dev warns CAPABILITY_NOT_IN_CATALOG for the id when it starts. For an OAuth provider's held-token calls there is no flow locally: the SDK puts the developer's own token from .dev.vars on the call, under the provider's prefix plus ACCESS_TOKEN (devAccessTokenName(): GOOGLE_WORKSPACE_ACCESS_TOKEN, GITHUB_OAUTH_ACCESS_TOKEN), and integrationStatus reports a connection while it is set; without it the call answers integration_not_connected as the Gateway would.

The catalog

Generated from CAPABILITIES by pnpm -C packages/cli docs:update; a test fails CI when it is stale. Step by step for each: the everyapp skill's setup/providers.md, under the provider's id (setup/providers.md#<id>), and the provider's own setup file where it has one.

The built-in catalog has 74 providers: 47 API-key, 9 AI, 18 OAuth clients.

OAuth clients (oauth_client: the Gateway completes their token endpoints only, and the spec parser takes none as a row): linkedin, facebook, instagram, threads, youtube, tiktok, tiktok-business, reddit, pinterest, discord, slack, mastodon, kick, twitch, tumblr, dribbble, google-workspace, microsoft-365. Their settings, consoles, redirect URIs, token endpoints and scope sets are generated in the capabilities document. Gateway services (service: no host, no spec): email, members.

Sources

• The catalog, the auth kinds and CapabilityLookup: packages/sdk/src/internal/capabilities.ts.
• The spec parser: packages/sdk/src/internal/providerSpec.ts. The row rules and the registry: packages/sdk/src/internal/providerRegistry.ts.
• The Gateway's registry and its host rule: apps/every-app-gateway/src/server/providers/index.ts; the table: apps/every-app-gateway/src/db/providers.schema.ts; the reads: apps/every-app-gateway/src/server/repositories/ProviderRepository.ts.
• The proxy and the order of its checks: apps/every-app-gateway/src/server/integration-proxy.ts, written out in the capabilities document.
• The commands: packages/cli/src/commands/provider/.
• The design and its decisions: docs/design/2026-10-provider-registry.md in the repository. The invariants: the threat model, B4.