Back to docsConnectors

Custom connectors

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

Last updated July 30, 2026 · 6 min read

The catalog covers 290+ 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 Okou how to call the service. From there, Okou 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 Okou 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 Okou to be able to request, and Okou 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 Okou 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 Okou to specific endpoints, like /v1/invoices/*. Reduces blast radius.
  4. Click Save and Test connection. Okou 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 Okou displays on the add-connector form.
  2. In Okou: 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 Okou is allowed to request. Use the minimum that covers your workflows.
  4. Save. The first chat that needs this connector triggers the OAuth flow per user.

Telling Okou how to use a custom connector

Two ways. Pick whichever fits your workflow.

Describe it inline when you ask Okou to do something:

"Use the internal-billing-api connector to fetch invoice #4422. Then email the PDF to [email protected]."

Okou 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 workflow that references the connector by name. The instruction describes the procedure; Okou loads the workflow automatically when its description matches an incoming request. For repeated work, this is cleaner than re-describing the connector inline every time.

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

OpenAPI specs and inline schemas

Okou 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 Okou at the URL.
  • Upload a spec. Paste or upload an OpenAPI 3 YAML/JSON. Okou 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, Okou 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 chat log with method, URL, status code, and timing.
  • Rate limits. Enforced by the upstream service. Okou handles 429 responses with exponential backoff up to a workspace-configured limit.
  • Allow-listed paths. Optional: restrict Okou 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 Okou rather than reusing your personal admin key. Easier to rotate and audit.
  • Missing schemas. Without an OpenAPI spec or inline description, Okou 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 chat.
  • Forgetting to rotate. Set a calendar reminder to rotate keys quarterly. Connector key rotation is one click in Okou; the upstream rotation is what takes most of the time.

What's next

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