BYO keys and tiers

Pipeworx has two layers of authentication, and they’re independent:

1. Gateway tier — your auth to Pipeworx (controls daily call quota)
2. Pack-level keys — keys for paid upstream sources (ATTOM, Altos, etc.) passed per-call as an underscore-prefixed argument, usually _apiKey

Gateway tiers

The limit counts tools/call. Keepalives and MCP discovery (initialize, tools/list, resources/list, prompts/list) run on a separate budget, so connecting and listing tools never spends it.

Resolution priority: Bearer token > X-API-Key > anonymous fallback. The gateway returns your effective tier in _meta.tier on every response.

Per-tool key arguments

Some packs wrap upstream APIs that have their own keys (FRED, ATTOM, Altos, Alpha Vantage, etc.). The pack’s inputSchema declares the key as an underscore-prefixed argument, and you pass it per call:

fred_get_series({
  series_id: "MORTGAGE30US",
  _apiKey: "your-fred-api-key"
})

_apiKey is the convention — around 240 packs use exactly that name.

But it is not universal, and the exception is not arbitrary. A compound tool calls several upstreams in one request, so it cannot have a single _apiKey: it needs one argument per vendor. housing-intel declares _attomKey, _fredKey, _blsKey and _hudKey; altos uses _altosKey; fintech-intel takes _fredKey and _avKey. A few packs need a pair rather than a single key — paypal wants _clientId + _clientSecret, twilio wants _accountSid + _authToken, woocommerce wants _apiKey + _apiSecret.

Read the argument name off the tool, not off this page. Two reliable sources, in order:

1. the tool’s own inputSchema in tools/list — the authoritative answer;
2. the message field of the API key required error, which names the exact argument, e.g. “Altos Research API key required. … pass via _altosKey.”

One caveat while a fix is in flight: the generic signup_hint attached to that same error currently says _apikey (lowercase) for every tool. JSON arguments are case-sensitive, so passing that name gets your key silently dropped and the identical “API key required” error back — with a valid key. Trust the message, not the signup_hint. Verified live 2026-08-10.

Whatever the argument is called, it is stripped from analytics — never logged with your usage data, and forwarded only to the upstream provider.

Why two layers?

• Pipeworx as a service has a tier system to fund the gateway’s hosting (CF Workers, KV, Anthropic for ask_pipeworx, etc.).
• Some upstream providers require the caller’s key for their own auth and billing. Pipeworx doesn’t proxy those — you pass through.

There are three cases, and it is worth knowing which one you’re in before you go looking for a key:

The quickest way to tell which case a tool is in is to call it without a key. A result means you don’t need one; an API key required error names the exact argument to pass.

Vertical bundling

Pipeworx Verticals (Housing, FinTech, etc.) can include managed access to paid sources. Subscribing to a vertical at pipeworx.io/account gives your account a single Bearer token that covers both the gateway tier and the upstream keys — Pipeworx fronts the upstream relationship.

So an account with a Housing Vertical subscription can call attom_avm without passing _apiKey — the gateway substitutes the managed key.

Get a free account

Sign up at pipeworx.io with GitHub. You get:

• 200 calls/day (vs 50 anonymous)
• Persistent remember / recall memory (vs 24-hour TTL)
• Account-scoped credit transactions visible at pipeworx.io/account
• The ability to subscribe to verticals

Get a paid account

Same Bearer token, unmetered usage with budget controls. Set up at pipeworx.io/account.

Quick auth checklist