OneCLI: Credential Gateway Architecture for AI Agents

AI agents need access to production APIs and databases, but you cannot put credentials directly into LLM context. The model will log them, leak them in error messages, or hallucinate them into responses. Traditional secret vaults assume humans will keep secrets safe. Agents cannot be trusted the same way.

OneCLI is a credential gateway that sits between agents and the tools they call. It intercepts tool invocations, validates the request against policy, retrieves the credential from a vault, injects it at execution time, and returns the result without ever exposing the secret to the agent’s context or logs.

The architecture addresses a specific security boundary problem: agents need to use secrets, but they should never see them.

Trust Boundary and Request Flow

OneCLI establishes three trust zones: the agent (untrusted), the gateway (trusted), and the vault (highly trusted). The agent can request tool execution, but it cannot read or write credentials directly.

Request flow:

1. Agent generates a tool call (e.g., query_database(table="users", filter="active=true")).
2. Gateway intercepts the call before execution.
3. Gateway validates the request against policy (which tools this agent can use, which parameters are allowed).
4. Gateway retrieves the credential from the vault (database connection string, API key).
5. Gateway injects the credential into the tool execution context.
6. Tool executes with the real credential.
7. Gateway returns the result to the agent, stripping any credential artifacts from the response.

The agent never receives the credential. It only sees the tool’s output.

Policy validation:

The gateway enforces rules like:

• Agent A can query the users table but not the payments table.
• Agent B can call the Stripe API but only for read operations.
• Agent C can access the production database only between 9 AM and 5 PM.

Policies are defined in a configuration file or pulled from an external policy engine (Open Policy Agent, AWS IAM). The gateway evaluates the policy before retrieving the credential, so unauthorized requests fail fast without touching the vault.

Credential Injection Without Context Exposure

The core technical challenge is injecting credentials at execution time without leaking them into the agent’s observable state. OneCLI uses a few techniques:

Environment variable injection:

For CLI tools and scripts, the gateway spawns a subprocess with the credential in an environment variable. The subprocess runs, produces output, and terminates. The environment variable is scoped to that process and does not persist.

import subprocess
import os

def execute_tool_with_secret(tool_command, secret_key, secret_value):
    env = os.environ.copy()
    env[secret_key] = secret_value
    
    result = subprocess.run(
        tool_command,
        env=env,
        capture_output=True,
        text=True
    )
    
    # Secret never appears in result.stdout or result.stderr
    return result.stdout

API client wrapping:

For HTTP APIs, the gateway wraps the client library and injects the credential into headers or request bodies. The agent calls a wrapper function, and the gateway handles authentication transparently.

def call_stripe_api(agent_id, endpoint, params):
    # Validate agent_id is allowed to call this endpoint
    if not policy_allows(agent_id, "stripe", endpoint):
        raise PermissionError("Agent not authorized")
    
    # Retrieve credential from vault
    api_key = vault.get_secret("stripe_api_key")
    
    # Inject into request
    headers = {"Authorization": f"Bearer {api_key}"}
    response = requests.post(
        f"https://api.stripe.com/{endpoint}",
        json=params,
        headers=headers
    )
    
    # Return sanitized response
    return response.json()

Database connection pooling:

For database queries, the gateway maintains a connection pool with pre-authenticated connections. The agent submits a query, the gateway selects a connection from the pool, executes the query, and returns the result. The connection string never leaves the gateway.

The agent’s tool call looks like this:

{
  "tool": "query_database",
  "parameters": {
    "query": "SELECT name, email FROM users WHERE active = true"
  }
}

The gateway translates this into:

connection = pool.get_connection("production_db")
cursor = connection.cursor()
cursor.execute(params["query"])
results = cursor.fetchall()
return results

The agent receives results, not the connection string.

Vault Integration and Credential Rotation

OneCLI integrates with standard secret vaults (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault). It does not store credentials itself. It acts as a proxy that retrieves secrets on demand.

Vault adapter pattern:

class VaultAdapter:
    def get_secret(self, secret_name):
        raise NotImplementedError

class HashiCorpVaultAdapter(VaultAdapter):
    def __init__(self, vault_url, token):
        self.client = hvac.Client(url=vault_url, token=token)
    
    def get_secret(self, secret_name):
        response = self.client.secrets.kv.v2.read_secret_version(
            path=secret_name
        )
        return response["data"]["data"]["value"]

class AWSSecretsManagerAdapter(VaultAdapter):
    def __init__(self, region):
        self.client = boto3.client("secretsmanager", region_name=region)
    
    def get_secret(self, secret_name):
        response = self.client.get_secret_value(SecretId=secret_name)
        return response["SecretString"]

The gateway configuration specifies which adapter to use. You can swap vaults without changing agent code.

Credential rotation:

When a credential rotates, the vault updates the secret. OneCLI retrieves the new value on the next tool call. No agent code changes are required. The gateway does not cache credentials long-term (it may cache for seconds to reduce vault load, but not across sessions).

If a credential is compromised, you revoke it in the vault, and all agents lose access immediately. You do not need to redeploy agent code or update configuration files.

Multi-Tenancy and Audit Trails

OneCLI supports multi-tenant deployments where multiple agents share the same gateway but have different permissions.

Tenant isolation:

Each agent has an identifier (agent ID, API key, or JWT). The gateway maps this identifier to a policy. Agent A’s policy grants access to database X, while Agent B’s policy grants access to database Y. The gateway enforces this at request time.

Audit logging:

Every tool call is logged with:

• Agent ID
• Tool name
• Parameters (sanitized to remove any user-provided secrets)
• Timestamp
• Result status (success, failure, policy violation)

Logs go to a centralized system (Splunk, Elasticsearch, CloudWatch). You can trace which agent accessed which resource and when. If an agent misbehaves, you can revoke its policy and review its access history.

Example log entry:

{
  "timestamp": "2026-07-24T08:15:32Z",
  "agent_id": "agent-prod-42",
  "tool": "query_database",
  "parameters": {
    "query": "SELECT * FROM users WHERE id = 123"
  },
  "policy_decision": "allowed",
  "vault_secret": "production_db_connection",
  "execution_time_ms": 45,
  "result_status": "success"
}

The vault_secret field identifies which credential was used, but the actual credential value is not logged.

Deployment Shape and Failure Modes

OneCLI runs as a sidecar or a centralized service. The sidecar pattern is simpler for single-agent deployments. The centralized service pattern is better for multi-agent systems where you want shared policy enforcement and audit trails.

Sidecar deployment:

The gateway runs in the same container or VM as the agent. The agent calls localhost:8080/execute_tool, and the gateway handles the rest. This minimizes network latency and simplifies authentication (the agent and gateway share a local socket or environment).

Centralized service:

The gateway runs as a standalone service. Multiple agents call it over HTTP or gRPC. You need to authenticate agents (API keys, mTLS, JWT) and handle rate limiting, retries, and failover.

Failure modes:

Failure Mode	Symptom	Mitigation
Vault unreachable	Tool calls fail, agent cannot proceed	Cache credentials for short TTL, degrade gracefully
Policy misconfiguration	Agent denied access to legitimate tool	Validate policies in CI, test with dry-run mode
Credential leak in logs	Secret appears in agent logs or LLM output	Sanitize all responses, redact patterns, audit logs
Gateway downtime	All tool calls fail	Deploy multiple gateway instances, use load balancer
Slow vault response	Tool calls time out, agent retries	Set aggressive timeouts, cache credentials, use async
Agent impersonation	Malicious agent uses stolen agent ID	Use short-lived tokens, rotate agent credentials, monitor anomalies

The most dangerous failure is credential leakage. If the gateway accidentally returns a credential in the tool output, the agent will see it and may log it or pass it to the LLM. OneCLI includes response sanitizers that scan for common secret patterns (AWS keys, database URLs, API tokens) and redact them before returning to the agent.

Observability and Debugging

You need visibility into what the gateway is doing. OneCLI exposes metrics and traces.

Metrics to track:

• Tool call rate per agent
• Policy denial rate
• Vault retrieval latency
• Cache hit rate (if caching credentials)
• Error rate by tool and agent

Tracing:

Each tool call gets a trace ID that flows through the gateway, vault, and tool execution. You can correlate agent behavior with gateway decisions and vault access.

Debugging a denied request:

1. Agent logs show tool call failed with 403 Forbidden.
2. Gateway logs show policy denial: Agent agent-prod-42 not allowed to call stripe_api with endpoint /charges.
3. Policy configuration shows agent-prod-42 only has read access to /customers.
4. Fix: Update policy to grant write access to /charges, or change agent code to use a different tool.

Without the gateway, you would see a generic authentication error from Stripe, and you would not know if the agent used the wrong credential, the wrong endpoint, or if the policy was misconfigured.

Comparison to Traditional Vaults

Traditional vaults (HashiCorp Vault, AWS Secrets Manager) assume the caller is trusted to handle secrets responsibly. You retrieve a secret, use it, and do not log it. Humans can follow this rule. Agents cannot.

Traditional vault workflow:

1. Agent retrieves database password from vault.
2. Agent connects to database using the password.
3. Agent logs the connection attempt (password may leak into logs).
4. Agent passes the password to the LLM as part of context (password definitely leaks).

OneCLI workflow:

1. Agent requests database query via gateway.
2. Gateway retrieves password from vault.
3. Gateway executes query with password.
4. Gateway returns query result to agent (password never exposed).

OneCLI is not a replacement for a vault. It is a layer on top of a vault that enforces the principle of least privilege for agents.

Technical Verdict

Use OneCLI if:

• You have agents that need to call APIs or databases with credentials, and you cannot trust the agent to handle secrets safely.
• You need fine-grained access control (agent A can query table X, agent B can query table Y) and you want to enforce it outside the agent’s code.
• You want centralized audit trails of which agents accessed which resources, without modifying every tool the agent uses.
• You are already using a secret vault (HashiCorp Vault, AWS Secrets Manager) and you want to extend it to support agent workloads without exposing credentials to LLM context.
• You need to rotate credentials frequently and you do not want to redeploy agent code every time a secret changes.

Avoid OneCLI if:

• Your agents only call public APIs that do not require authentication, or they use OAuth flows where the agent never sees the token.
• You have a single agent with a single credential and you can hardcode it in a secure environment variable (the gateway adds unnecessary complexity).
• You need sub-millisecond latency for tool calls and you cannot tolerate the overhead of policy evaluation and vault retrieval on every request.
• Your tools require interactive authentication (OAuth consent screens, MFA) that cannot be automated through a gateway.
• You trust your agents completely and you have other mechanisms (sandboxing, network isolation) to prevent credential leakage.

OneCLI solves a real problem: agents need secrets, but they should not see them. The architecture is straightforward (intercept, validate, inject, return), but the implementation details matter. You need robust policy validation, response sanitization, and observability to prevent credential leaks. If you are building production agents that access sensitive systems, a credential gateway is not optional. It is a necessary security boundary.

Source Links

• OneCLI on Hacker News (Show HN, 94 points)
• Agent Security Is a Systems Problem (arXiv:2605.18991)
• HashiCorp Vault Documentation