Back to docsConnectors

Custom connectors

Add a custom connector with an API key or OAuth credential.

Last updated May 27, 2026 · 6 min read

The catalog covers 100+ services, but every team has a few internal tools or regional SaaS products that aren't on it. Custom connectors solve that.

You register a credential — an API key or OAuth credentials — and tell Zero how to call the service. From there, Zero treats your custom connector identically to a built-in one: same audit log, same brokered-access proxy, same sensitive-action gates.

Two flavors

Pick the type that matches your service:

  • API key — works for any service that authenticates with a static token in a header. The simplest and fastest path: paste the key, name the connector, point Zero at the base URL. Most internal APIs and many SaaS tools use this.
  • OAuth 2.0 — for services that issue per-user tokens via OAuth. You provide a client ID and secret, configure the scopes you want Zero to be able to request, and Zero runs the OAuth dance per-user when needed.

If you're not sure which to use, check the upstream service's API docs. The word "API key" (or "personal access token") usually means flavor 1; "OAuth" (or "client credentials") usually means flavor 2.

Setting up an API-key connector

  1. Open the Connectors page in your workspace.
  2. Click Add custom connector → API key.
  3. Fill in:
    • Name. Something Zero can recognize when reading prompts, e.g., internal-billing-api or acme-crm.
    • Base URL. The root of the API: https://api.internal.acme.com.
    • Auth header. Usually Authorization: Bearer YOUR_TOKEN or X-API-Key: YOUR_TOKEN. Match what the service expects.
    • API key. Paste the credential. Stored encrypted; never visible after save.
    • Allowed paths (optional). Restrict Zero to specific endpoints, like /v1/invoices/*. Reduces blast radius.
  4. Click Save and Test connection. Zero pings the base URL with a GET / (or a path you specify) and reports the response.

Setting up an OAuth 2.0 connector

A bit more work, but worth it for services where per-user authorization matters:

  1. Register an OAuth application with the upstream service. You'll get a client ID and client secret. Set the redirect URI to the one VM0 displays on the add-connector form.
  2. In VM0: Add custom connector → OAuth 2.0.
  3. Fill in:
    • Name and Base URL, as above
    • Authorization URL and Token URL from the upstream service's OAuth docs
    • Client ID and Client secret
    • Scopes. The list of scopes Zero is allowed to request. Use the minimum that covers your workflows.
  4. Save. The first session that needs this connector triggers the OAuth flow per user.

Telling Zero how to use a custom connector

Two ways. Pick whichever fits your workflow.

Describe it inline when you ask Zero to do something:

"Use the internal-billing-api connector to fetch invoice #4422. Then email the PDF to ops@acme.com."

Zero loads the connector spec and figures out which endpoint to call. This works because connectors come with OpenAPI-style metadata (auto-discovered for many services, optionally provided manually).

Write a skill that references the connector by name. The skill body describes the procedure; Zero loads the skill automatically when the description matches an incoming request. For repeated workflows, this is cleaner than re-describing inline every time.

A skill named pull-invoice with description "fetch an invoice from internal-billing-api and email the PDF" — once written, Zero invokes it whenever someone asks for an invoice.

OpenAPI specs and inline schemas

Zero works best with a custom connector when it knows the available endpoints, methods, and parameters. Three ways to supply that:

  • Auto-discover from the service's /openapi.json or /swagger.json if it exposes one. Just point Zero at the URL.
  • Upload a spec. Paste or upload an OpenAPI 3 YAML/JSON. Zero parses it and offers tooltip-style metadata when crafting calls.
  • Inline descriptions. For internal tools without specs, you can write a short markdown description in the connector body — endpoints, methods, sample payloads. Crude but functional.

Without a spec, Zero still works — it just has to guess more about parameter shapes. For frequently used custom connectors, a spec pays back quickly.

Sharing across workspaces

Custom connectors are workspace-scoped by default. Two teams in the same org can each maintain their own custom connector for the same internal API. For organizations that want one canonical setup:

  • Enterprise org-level connectors. Available on enterprise plans. Set up once at the org level; appears in every workspace under that org. Recommended for internal APIs everyone uses.
  • Connector package. For very large orgs, the internal platform team can publish a custom connector as a versioned package; workspaces install it and pick up updates automatically.

Security and rate limits

  • Credentials. Encrypted at rest with per-workspace keys. Never visible after save; only re-enterable.
  • Per-call audit. Every request through a custom connector appears in the session log with method, URL, status code, and timing.
  • Rate limits. Enforced by the upstream service. Zero handles 429 responses with exponential backoff up to a workspace-configured limit.
  • Allow-listed paths. Optional: restrict Zero to specific URL patterns. Reduces blast radius if a connector key is over-privileged.
  • Read-only by default. A new custom connector is marked read-only. Granting write access requires explicit configuration per workspace.

Common pitfalls

  • Over-broad API keys. If your service supports it, mint a scoped key for Zero rather than reusing your personal admin key. Easier to rotate and audit.
  • Missing schemas. Without an OpenAPI spec or inline description, Zero guesses parameter shapes. That works for simple cases and breaks for nested objects. Provide a spec when you can.
  • Untested base URLs. Always click Test connection after setup. A 401 or 404 at this stage is far better than a 401 in a critical session.
  • Forgetting to rotate. Set a calendar reminder to rotate keys quarterly. Connector key rotation is one click in VM0; the upstream rotation is what takes most of the time.

What's next

  • See Skills for capturing repeated custom-connector workflows.
  • See Permissions for how custom-connector credentials are handled.
  • See the Catalog before building custom — your service may already be supported.