How to Secure Your API Keys for Agent Use

The problem

Your agent needs API keys to do useful work. Send an email through Resend, charge a card through Stripe, create a ticket in Linear — every capability requires a credential.

The default behavior is terrifying: paste the key into a config file, hope nobody reads it.

Most credential advice is written for human developers deploying web apps. Agents are different. They run unattended, make autonomous decisions about which keys to use, and often operate across multiple services in a single workflow. The attack surface is wider and the human oversight is narrower.

This guide covers what actually works.

Three credential paths

There's no single right answer. The right approach depends on how much you trust the infrastructure, how much operational control you want, and whether provider control or governed execution is the point.

Bring Your Own Key (BYOK)

You pass your existing API key to the tool or agent framework. The key stays under your control.

# Environment variable (recommended for servers/CI)
export STRIPE_API_KEY=sk_live_...

# MCP server config (Claude Desktop example)
{
  "mcpServers": {
    "rhumb": {
      "command": "npx",
      "args": ["rhumb-mcp@latest"],
      "env": {
        "RHUMB_API_KEY": "rhumb_live_..."
      }
    }
  }
}

When to use it: You already have accounts with the services you need. You want full control over credentials and billing. You're comfortable managing key rotation. Security posture: The key is only as safe as where you store it. OS keychain > environment variable > config file > hardcoded string.

Managed capabilities

Rhumb holds the service credential and delivers the capability. You never touch the underlying API key.

# You call Rhumb. Rhumb calls the service.
curl -X POST https://api.rhumb.dev/v1/capabilities/email.send/execute \
  -H "X-Rhumb-Key: rhumb_live_..." \
  -d '{"to": "user@example.com", "subject": "Hello"}'

When to use it: You don't want to manage individual service accounts. You want Rhumb to handle authentication, rate limits, and failover. You want per-call pricing with route, health, and cost checks before execution. Security posture: You trust Rhumb with the service credential. You don't need to store or rotate individual service keys. Your governed API key is the only credential to protect.

Agent Vault

Rhumb stores or brokers the provider credential for you and injects it at call time, so the workflow can still touch your own systems without spraying raw provider secrets across every agent runtime.

When to use it: You need provider control or access to your own systems of record, but you want a tighter trust boundary than raw BYOK everywhere. This is the middle path between fully managed Rhumb rails and handing every runtime a live upstream key. Security posture: The agent still uses your systems, but the raw provider secret stays behind the vault boundary. You reduce copy-paste exposure and make rotation or revocation more surgical.

Credential format is not the authority boundary

OAuth versus API key is the visible choice. For agents, it is not the deepest security decision. The deeper question is whether the credential maps to a containment principal the operator can reason about before the model touches production state.

Ask these questions before calling a credential strategy safe:

Which principal executes the call? A shared OAuth app, one workspace user, one service account, and one per-agent key create different blast radii even if all four authenticate cleanly.

Which tools stay hidden until that principal exists? Discovery should narrow after auth, not advertise write-capable surfaces the caller cannot safely use.

Whose quota and budget burn? If three agents share one upstream account, the system still has to attribute spend, rate-limit pressure, and failures to the original actor.

Can a dangerous neighbor be denied? The useful proof is not a valid token. It is the same caller making a safe scoped call and getting a typed denial for the adjacent out-of-scope target.

Treat OAuth as ceremony, API keys as bearer power, and vaults as custody. None of them replace scoped execution policy, narrow discovery, typed denials, and trace evidence.

x402 is a payment path, not a credential mode

No account signup on this rail. Payment proof authorizes the request. For repeat traffic, default to governed API key or wallet-prefund on X-Rhumb-Key, and bring BYOK or Agent Vault only when provider control is the point.

# First call: get payment instructions
curl -X POST https://api.rhumb.dev/v1/capabilities/email.send/execute
# Returns 402 with USDC payment details

# After paying on-chain:
curl -X POST https://api.rhumb.dev/v1/capabilities/email.send/execute \
  -H 'X-Payment: {"tx_hash":"0x...","network":"base","wallet_address":"0x..."}'

When to use it: Your agent has a crypto wallet and you want zero-signup, request-level payment authorization. Use this when per-call payment is the point, not as the default repeat-throughput path. Security posture: No credential to steal. The wallet's private key is the only secret, and it stays on the agent's machine. Replay protection via unique transaction hashes.

Credential storage hierarchy

Not all storage is equal. Here's the ranking from most to least secure:

OS keychain example (macOS)

# Store
security add-generic-password -a "rhumb" -s "RHUMB_API_KEY" -w "rhumb_live_..."

# Retrieve at runtime
RHUMB_API_KEY=$(security find-generic-password -a "rhumb" -s "RHUMB_API_KEY" -w)

Environment variable example (Docker)

# Don't bake keys into images. Pass at runtime.
docker run -e RHUMB_API_KEY=rhumb_live_... my-agent

What we protect against (and what we don't)

Honest security requires honest threat modeling.

Rhumb protects against:

• Credential exposure in logs and prompts — keys are injected at the HTTP layer, never surfaced in agent conversation history
• Replay attacks on x402 payments — unique transaction hash constraint
• Rate limit abuse per wallet (x402) or per API key (registered)
• Accidental credential leakage in tool outputs — response sanitization strips auth headers

Rhumb does NOT protect against:

• A compromised machine — if an attacker has root access, all credentials on that machine are exposed regardless of storage method
• Malicious agent code — if the agent framework itself is compromised, it can read any credential the agent has access to
• Social engineering — if someone tricks you into sharing your API key, that's outside Rhumb's control

We don't use phrases like "enterprise-grade security" or "bank-level encryption" because they don't mean anything specific. We tell you exactly what the boundaries are.

Best practices checklist

Use scoped keys. If a service offers read-only or capability-scoped API keys, use the narrowest scope that works.

Bind keys to principals and budgets. Store who owns the key, which agent may use it, which tenant/workspace it can touch, and whose quota burns when the call executes.

Rotate regularly. Set a calendar reminder. Quarterly at minimum.

Never commit keys to git. Use .env files with .gitignore, or better yet, use a secret manager reference.

One key per agent. If you run multiple agents, give each one its own API key. Makes revocation surgical.

Monitor usage. Rhumb's API shows per-key execution history. Watch for anomalies.

Prefer Rhumb-managed, Agent Vault, or x402 over raw BYOK when possible. Fewer raw credentials in more places = smaller attack surface.

Use secret references in config, not raw values. Instead of the key itself, store a reference to where the key lives:

{
  "rhumb_api_key": "op://Shared/Rhumb/credential"
}

The bottom line

The safest credential is the one that doesn't exist. x402 is the no-credential payment rail when per-call payment is the point. Managed capabilities reduce your credential surface to a single governed API key. Agent Vault is the middle path when you need provider control without exposing raw provider secrets everywhere. BYOK gives you full control when you need it.

Pick the path that matches your trust model. Store credentials in the highest-security option available. Be specific about what you're protecting against.

Your agents are only as secure as their weakest credential.