Your AI Agent Shouldn't Hold Your OAuth Tokens

A developer from the OpenConnector project proposes a connector gateway architecture to keep OAuth tokens and provider credentials out of AI agents' reach. The open-source Apache-2.0 project, which has surpassed 4,000 GitHub stars, offers over 1,000 providers and 10,000 prebuilt Actions, and uses explicit Action contracts to separate agent decision-making from credential handling. The developer demonstrates a local setup via Docker and shows how agents can discover, inspect, and execute Actions without holding secrets.

An agent that can only chat is easy to contain. An agent that can read Gmail, open GitHub issues, update Notion, and send Slack messages is much more useful—and much harder to secure. The uncomfortable part is not the tool call itself. It is everything around it: For a small internal script, putting an API key in an environment variable may be enough. For a product that connects agents to many user accounts, it becomes a weak architectural boundary. This article looks at a different approach: place authentication and provider-specific execution behind a connector gateway, then let the agent work with explicit Action contracts. I will use OpenConnector https://github.com/oomol-lab/open-connector , an Apache-2.0 open-source project, as the concrete example. At the time of writing, its GitHub repository has passed 4,000 stars—a useful signal that the problem resonates with developers, although popularity is not a substitute for evaluating the code, security model, and provider coverage yourself. Suppose an agent needs to fetch the current GitHub user. The agent needs to know that an Action exists, what input it accepts, and what output it returns. It does not need the personal access token used to authorize the request. Those are two separate responsibilities: Agent decides what to do selects an Action produces structured input | v Connector gateway selects the requested connection applies credentials enforces policy calls the provider records a redacted run result | v Provider API This boundary does not solve every agent-security problem. Prompt injection can still cause a bad tool choice. An overly broad OAuth scope is still overly broad. A compromised gateway is still serious. What the boundary does provide is a single place to store and rotate credentials, restrict Actions, separate accounts, and inspect execution. That is easier to reason about than passing provider secrets through every agent host and tool implementation. OpenConnector combines several pieces that otherwise tend to grow independently: The project currently advertises more than 1,000 providers and more than 10,000 prebuilt Actions. Treat those numbers as catalog scale, not as a guarantee that every provider has every operation you need. Before adopting any integration platform, check the exact Actions, scopes, and edge cases required by your product. The simplest test does not require an account or a credential. Clone the repository, then start the published container: docker compose up The Compose file pulls ghcr.io/oomol-lab/open-connector:latest . When the runtime is ready, the local console is available at http://localhost:3000 , and the generated API reference is at http://localhost:3000/docs . Hacker News provides a convenient no-auth Action: curl -s -X POST \ http://localhost:3000/v1/actions/hackernews.get top stories \ -H 'content-type: application/json' \ -d '{"input":{}}' Before executing anything, a client can discover the catalog: curl -s http://localhost:3000/v1/actions curl -s "http://localhost:3000/v1/actions?service=hackernews" It can also request a compact, agent-readable guide for one Action: curl -s \ http://localhost:3000/api/actions/hackernews.get top stories/agent.md This discover-inspect-execute pattern matters. Loading thousands of tool definitions into an agent context is wasteful and can make tool selection worse. A small discovery surface lets the agent search first, inspect only the relevant contract, and execute after it understands the input. The local MCP endpoint follows that model. Rather than exposing one MCP tool for every catalog Action, it provides a small set of tools for listing apps and connections, searching Actions, retrieving an Action guide, and executing an Action. GitHub is a straightforward authenticated example because it can use a personal access token. In a local development environment, store a connection through the administration API: curl -s -X PUT http://localhost:3000/api/connections/github \ -H 'content-type: application/json' \ -d '{ "authType": "api key", "values": { "apiKey": "github pat ..." } }' Now execute an Action without including that credential in the request: curl -s -X POST \ http://localhost:3000/v1/actions/github.get current user \ -H 'content-type: application/json' \ -d '{"input":{}}' For multiple GitHub accounts, create named connections such as personal and work . The caller selects the intended connection explicitly. A missing named connection returns an error instead of silently falling back to another account—a small behavior that prevents surprisingly dangerous mistakes. OAuth providers require more setup when self-hosting. You must register your own OAuth app, configure its callback URL, protect the client secret, and operate the token lifecycle. OpenConnector centralizes that work, but it does not make those responsibilities disappear. If you do not want to register and maintain OAuth applications for every provider, OOMOL-hosted connectors https://oomol.com/docs/connector-saas/ provide the SaaS version of the same model. OOMOL supplies the OAuth applications and runs the connector infrastructure, so you can let users authorize supported accounts without first applying for provider client credentials yourself. Users still complete the provider's normal consent flow; “managed OAuth” means the application credentials and runtime are operated for you, not that authorization is bypassed. That makes the hosted path useful for validating a product or shipping integrations quickly. The tradeoff is that execution depends on a third-party service and its pricing, availability, and data-handling terms. Because the hosted and open-source runtimes use the same provider IDs, Action IDs, and contracts, a team can start with managed connectors while keeping a path toward private deployment later. Getting a successful API response is only the first test. Before connecting real accounts, I would check the following controls. The Web Console, /api/ , and documentation endpoints can be protected with an admin token. Agent-facing /v1/ and /mcp calls use runtime tokens or configured JWT access tokens. Do not expose the administration surface with the same trust level as an agent runtime. OpenConnector supports allowed and blocked Action patterns. A research agent may need read operations but no message-sending or record-deletion Actions. Encode that difference as policy instead of relying only on the system prompt. Provider proxy access is controlled separately from Action access. This distinction is useful: permission to execute a curated GitHub Action should not automatically become permission to send arbitrary requests to GitHub's API. The local runtime stores state in SQLite by default. OOMOL CONNECT ENCRYPTION KEY enables encryption for stored credentials, OAuth client configuration, and completed idempotent responses. Encryption is only one part of operations. The deployment still needs a plan for key management, file permissions, backups, host access, rotation, and incident response. Redacted run records are useful for answering “what did the agent do?” without intentionally storing raw credentials. They can still contain provider names, Action IDs, account labels, timing, errors, and business context. Decide who can read them and how long they should be retained. The HTTP Action endpoint accepts an Idempotency-Key . Retrying the same Action, input, and connection with the same key can replay a completed result instead of executing it again. That is helpful for operations such as creating a record or sending a message, but it is not a guarantee of exactly-once execution by the upstream provider. MCP Action execution also does not accept the HTTP idempotency header. Workflow code still needs to handle uncertain outcomes deliberately. OpenConnector can run locally with Node.js or Docker, on Docker infrastructure such as Fly.io, or on Cloudflare Workers with D1, R2, and Static Assets. There is also an OOMOL-hosted path. The right choice is mostly about responsibility: | Model | You control | You operate | |---|---|---| | Local or self-hosted | Runtime, data, credentials, network boundary | OAuth apps, secrets, storage, backups, upgrades | | Cloudflare deployment | Worker account and Cloudflare resources | D1/R2 setup, OAuth apps, secrets, migrations, deployment | | Managed OOMOL runtime | Application behavior and connections | Less infrastructure; depends on a hosted service and its pricing | Self-hosting is valuable when credential location, network access, or compliance requires private infrastructure. It is not automatically cheaper once operational work is counted. A managed service is faster to start, but it adds an external dependency. There is no universally correct answer. A gateway adds another service, another failure boundary, and another component to upgrade. If your application has one provider, one account, and three stable API calls, the provider's official SDK may be the simplest and best solution. The gateway approach starts to pay for itself when several of these become true: Architecture should follow the problem, not the catalog size. If you are considering OpenConnector—or any connector platform—test it with one real workflow and answer these questions: The answers are more important than the number of logos on an integrations page. OpenConnector is available on GitHub https://github.com/oomol-lab/open-connector . The best places to continue are the quick start https://github.com/oomol-lab/open-connector/blob/main/docs/quickstart.md , the Runtime API and MCP reference https://github.com/oomol-lab/open-connector/blob/main/docs/runtime-api.md , and the credential documentation https://github.com/oomol-lab/open-connector/blob/main/docs/credentials.md . If your agents already use external services, where do you draw the credential boundary today? Disclosure: This article was prepared with AI assistance and reviewed against the linked project documentation. The human author is responsible for the final claims and examples.