AI Agent Secrets Management with Cloudflare Secrets Store

AI agent secrets management works best when an agent never receives a reusable provider key. Put the long-lived secret in Cloudflare Secrets Store, bind it only to a trusted Worker, and let that Worker perform a narrowly allowed action or exchange the secret for a short-lived credential. Cloudflare Access can identify the calling machine, while a credential broker can enforce which agent may request which action. These layers solve different problems, and you need all of them for a useful boundary.

This guide shows a generic design for support, deployment, and reporting bots. It explains what Cloudflare provides, what you must build yourself, and how to test rotation and failure paths. Cloudflare Secrets Store is in open beta as of August 3, 2026, so verify current product limits before using the design in a production system.

The three jobs: storage, identity, and action authorization

Many secret-handling designs fail because they treat one security control as if it does everything. A vault is not an identity system. A machine identity is not permission to run every action. A private network path is not a vault.

Use three separate questions:

1. Where is the reusable secret stored? Cloudflare Secrets Store can hold encrypted, reusable, account-level secrets. A Worker can read a bound value when it needs to call an upstream service.
2. Who is calling? Cloudflare Access service tokens can give a machine an outer identity. Access can reject traffic that does not satisfy the application policy.
3. What may this caller do right now? Worker code or a custom credential broker must check the agent, requested action, target, method, limits, and time window.

Think of a hotel. The safe stores the master key. The front desk checks who you are. Your room assignment decides which door you may open. Passing one check should never silently pass the other two.

This split is the heart of zero trust AI agents. “Zero trust” does not mean trusting nothing. It means every request must prove enough context, and access stays as small and short as practical.

Why environment files and master keys fail

An environment variable is not automatically unsafe. A Worker secret used by one small Worker can be a sensible choice. The dangerous pattern is a broad environment file or shared master key copied to every agent host.

Suppose three bots share one file containing a ticketing key, a deployment key, and an analytics key. The support bot needs only the ticketing key, but a prompt injection or stolen process can now read all three. Rotation is also painful. Every host must receive the new file at the right time, and old copies may remain in backups, shell history, build logs, or developer machines.

Shared master keys create four problems:

• Wide blast radius. One leak can unlock unrelated systems.
• Weak attribution. Logs show the same identity for several bots.
• Hard rotation. Changing one value can break every agent at once.
• Accidental disclosure. Debug output, crash reports, and tool results can return the raw value to a model or user.

Do not commit production environment files, local development variables, or generated secret bundles. A private repository reduces exposure, but it does not change the basic rule. Git history is designed to remember old content, which is the opposite of secret deletion.

What Cloudflare Secrets Store does

Cloudflare describes Secrets Store as a place for encrypted, reusable secrets at the account level. A stored secret can be reused through supported integrations without copying the plaintext value into application configuration. As of August 3, 2026, the current integrations are Workers and AI Gateway.

For a Worker integration, you create a secret in the store, give it a scope, and bind it to a Worker. Worker code reads the value at runtime with an asynchronous call such as:

const providerKey = await env.PROVIDER_API_KEY.get();

Two permission checks matter. The caller needs enough account authorization, and the secret’s own scope must permit the integration. Both must pass. The current scope values are workers and ai-gateway.

Cloudflare’s Secrets Store access roles also separate viewing from use. The Read permission exposes secret metadata, not the secret value, and it cannot bind a secret to an integration. Edit permission is required to create bindings. This is useful because an auditor may need to see names, scopes, and timestamps without gaining the power to attach a production secret to new code.

Secrets Store audit logs record operations such as access, creation, update, and deletion in the store. They do not automatically record every downstream API call that your Worker makes after reading a secret. Your application still needs an action log.

What the product does not do

Cloudflare Secrets Store is a storage and integration feature. It does not automatically provide a complete credential broker policy engine.

The following controls are custom application patterns, not built-in Secrets Store features:

• Ed25519 request signatures
• one-time nonces
• per-agent action allowlists
• five-minute credentials
• body hash verification
• downstream rate limits
• automatic compromise detection

You may choose some or all of these controls, but describe them honestly. Saying that Secrets Store “issues five-minute credentials” would be wrong. A custom broker or an upstream provider does that work.

Cloudflare Tunnel also has a different job. Tunnel can provide a private transport path from Cloudflare to an origin without opening a public inbound port. It does not store secrets and does not decide which downstream action an AI agent may run. Tunnel is transport, not a vault.

Finally, per-Worker secrets are different from account-level Secrets Store secrets. A normal Cloudflare Worker secret belongs to that Worker and is managed with Worker configuration. Secrets Store holds an account-level reusable value that can be bound through supported integrations. Pick the smaller tool when reuse and central binding governance are not needed.

Reference architecture

A practical design has five parts:

1. The AI agent decides that it needs an approved capability, such as reading one ticket or starting one deployment.
2. Cloudflare Access checks the outer machine identity, often with a service token policy.
3. A Worker or credential broker maps that identity to allowed actions and validates the request.
4. Cloudflare Secrets Store supplies the reusable provider key only to bound server-side code.
5. The upstream provider receives the narrow call and returns a result or its own short-lived credential.

The safest proxy pattern keeps the provider key inside the Worker. The agent sends a small request such as GET /v1/tickets/123, the Worker uses the key server-side, and the agent receives only a filtered ticket response.

Sometimes direct provider access is necessary. In that case, the Worker can use the reusable key to ask the provider for a short-lived credential with a narrow scope. The agent receives the short token, not the root key. This works only if the provider supports a secure exchange or session API.

Native design versus custom broker

A native-only design can be enough when one Worker owns a small set of fixed actions. Bind the secret to that Worker, protect the route with Access, and enforce action rules in Worker code. There is less infrastructure to operate.

A custom credential broker becomes helpful when many agents and providers need shared policy, short-lived credential exchange, centralized rate limits, approval workflows, or consistent audit records. The broker adds flexibility, but it also becomes a sensitive service. Its database, signing material, policy deployment, and availability need their own controls.

Do not add a broker just to make the diagram look advanced. Add it when it creates a clear boundary that cannot stay simple inside one Worker.

Example bot policy matrix

Start with jobs, not secret names. The agent should ask for a business action, and policy should map that action to the smallest provider capability.

This matrix makes a common mistake visible. If all three bots use the same provider key and the Worker accepts arbitrary URLs, the policy is only decoration. The code must construct approved upstream requests itself. Never let an agent supply an unrestricted provider host, path, or authorization header.

Signed request lifecycle

Cloudflare Access service tokens can prove that the request came through an approved machine identity. For higher-risk actions, an application signature can also prove possession of an agent-specific private key and protect the exact request contents.

A generic lifecycle looks like this:

1. The agent creates a request with an action name, target ID, timestamp, and random nonce.
2. It hashes the canonical request body.
3. It signs a canonical string with its private Ed25519 key.
4. Access checks the service token against the application policy.
5. The broker looks up the public key for the Access identity.
6. The broker verifies the signature, allowed clock window, body hash, and nonce.
7. The broker checks the action allowlist and any target-specific rule.
8. The Worker reads the bound secret and calls a fixed upstream endpoint.
9. The response is filtered, logged, and returned without the reusable key.

Ed25519 is a public-key signature system. The agent keeps the private key. The broker stores only the public key needed for verification. A nonce is a random value used once. Saving used nonces for the allowed time window stops a captured request from being replayed.

Signatures are not a replacement for Access. Access is useful at the edge, before application code runs. The signature is useful inside the application because it binds the actor to the method, path, body, and time.

Build guide

1. Define one narrow action

Choose a concrete operation, such as report.read_summary. Write down the upstream method, path template, allowed fields, maximum result size, and which agents may call it. Avoid a generic action such as provider.request, because it often becomes a tunnel around policy.

For each action, decide whether the Worker will proxy the call or return a provider-issued short token. Proxying is usually simpler and keeps the credential away from the agent.

2. Create a scoped account secret

Create the provider key in Cloudflare Secrets Store and select the workers scope for a Worker binding. Use a name that describes the provider role without embedding the actual value. Limit who has Edit permission because Edit is needed to bind secrets. Read-only users can inspect metadata, but they cannot bind the value.

The provider key itself should also be narrow. A vault cannot make an administrator key read-only. Configure the upstream provider role so the credential can perform only the calls your Worker needs.

3. Bind the secret to one Worker

Create a Secrets Store binding for the Worker that owns the action. Do not bind every account secret to a shared utility Worker. Bind only what the code needs.

The exact dashboard or API steps can change during an open beta, so use the current Cloudflare documentation and API reference. Treat infrastructure configuration as code where possible, but keep values out of the repository.

4. Use the key only on the server

The Worker should fetch the bound value, build a fixed upstream request, and return a filtered result. It must not return the key in JSON, headers, error text, or logs.

export default {
  async fetch(request, env) {
    const identity = request.headers.get("cf-access-authenticated-user-email");
    const input = await request.json();

    if (!identity || input.action !== "report.read_summary") {
      return Response.json({ error: "forbidden" }, { status: 403 });
    }

    const providerKey = await env.PROVIDER_API_KEY.get();
    const upstream = await fetch("https://api.example.com/v1/reports/summary", {
      method: "POST",
      headers: {
        authorization: `Bearer ${providerKey}`,
        "content-type": "application/json"
      },
      body: JSON.stringify({ period: input.period })
    });

    if (!upstream.ok) {
      return Response.json({ error: "upstream request failed" }, { status: 502 });
    }

    const data = await upstream.json();
    return Response.json({ total: data.total, period: data.period });
  }
};

This sample is intentionally small. Production code still needs schema validation, Access policy checks, timeouts, response size limits, rate limits, and safe error handling. The important shape is that the raw key crosses only from the binding into the upstream authorization header.

5. Protect the route with Cloudflare Access

Create an Access application for the broker or Worker route. Give each machine its own service token when separate revocation and attribution matter. The service token is the outer machine identity. It is not the downstream provider credential.

Access policies decide which service identities may reach the application. Your Worker or broker must still decide which action each identity may perform. Avoid one shared token for every bot, because you lose clean revocation and logs.

Never place service token values in source code or an agent prompt. Load them through the runtime’s protected secret mechanism. In a local development setup, keep development values out of Git and use credentials that cannot reach production.

6. Add an action policy

A simple policy document can map an agent identity to actions and limits:

{
  "agents": {
    "deployment-bot": {
      "actions": ["deploy.start", "deploy.status"],
      "targets": ["service-a", "service-b"],
      "environments": ["staging", "production"],
      "requestsPerMinute": 10,
      "requiresApproval": ["production"]
    }
  }
}

Treat this as application policy, not a Cloudflare Secrets Store schema. Validate the action and target using exact values. Do not use broad prefix checks such as “starts with deploy” when new actions might later appear beneath that prefix.

For production changes, an approval record can include the service, version, environment, approver, and expiration. The broker should verify that record at action time instead of trusting a sentence in the agent’s prompt.

7. Add signatures and nonces where risk justifies them

Create one Ed25519 key pair per agent. Register the public key with the broker and keep the private key outside the model’s readable context. Canonicalize the request before signing so both sides produce the same bytes.

A signed message might include:

POST
/v1/actions
2026-08-03T15:04:05Z
random-one-time-value
sha256-of-body

Reject timestamps outside a short clock window. Store the nonce with the agent ID until that window closes, and reject duplicates. Include the HTTP method, path, and body hash so an attacker cannot move a valid signature to a different action.

8. Choose proxying or short-lived credentials

Use proxying when the agent needs a result, not direct provider access. The broker keeps the reusable key and returns a filtered response. This gives the strongest control over paths, fields, and output.

Use a short-lived credential when the agent must connect directly to another service or handle a long-running transfer. Ask the upstream provider to create a narrow session, ideally limited by action, resource, and time. Five minutes is a common custom target, but it is not a Secrets Store feature and may be wrong for your job.

Never invent a short token by encrypting the long-lived key and sending it to the agent. That still exposes the reusable secret once decrypted. A true short-lived credential must be independently revocable or expire at the provider or broker enforcement point.

9. Rate limit and audit decisions

Set limits per agent and per high-risk action. A reporting bot may run a few large reports per hour. A support bot may need more small reads. A deployment bot should have a very low production change limit.

Log the time, agent identity, action, target, policy version, decision, result class, and request correlation ID. Do not log authorization headers, secret values, full sensitive request bodies, or full provider responses.

Keep two audit layers clear:

• Secrets Store audit logs tell you about store access, creation, updates, and deletion.
• Application logs tell you which agent requested which downstream action and whether it succeeded.

You need both to answer an incident question. A store log alone cannot prove every API call made with a value after it was read.

Rotation and incident containment

Rotation should be a rehearsed workflow, not an emergency invention. Record who owns the provider key, how to create a replacement, which Worker bindings use it, how to test the new value, and how to revoke the old one.

A safe rotation can follow these steps:

1. Create a replacement credential at the provider with the same or smaller scope.
2. Update the Secrets Store value or create a new version according to the current product workflow.
3. Test the Worker with a harmless allowed action.
4. Watch errors and authorization failures.
5. Revoke the old provider credential.
6. Confirm that an old credential test fails.
7. Save an incident or change record without storing the secret.

Compromised deployment bot example

Imagine that a deployment bot’s runtime is stolen. First, disable its Access service token so new requests fail at the edge. Then disable the agent in broker policy and revoke its Ed25519 public key registration. Cancel outstanding production approvals and short-lived sessions. Review application logs for the bot’s action history and Secrets Store logs for unexpected binding or value operations.

If the bot never received the reusable deployment key, you may not need to rotate that key. Rotate it anyway if logs show possible Worker compromise, an unexpected binding, raw key disclosure, or uncertainty about the boundary. Reissue the bot identity only after rebuilding the runtime from a known-good image.

This is the blast-radius advantage. A stolen bot identity can be isolated without breaking support and reporting bots. The design does not make compromise harmless, but it gives responders smaller switches to turn off.

Failure tests to run before launch

Happy-path tests prove that code works. Failure tests prove that the boundary works.

• Send no Access service token. Expect rejection before the protected action runs.
• Use the support bot identity for a deployment action. Expect a policy denial.
• Sign a request, then change the body. Expect signature verification to fail.
• Replay the exact nonce and signature. Expect the second request to fail.
• Use an expired timestamp or short-lived credential. Expect denial.
• Request an unlisted target or environment. Expect denial.
• Try to bind a secret with Read permission only. Expect the operation to fail because Edit is required.
• Give the Worker caller authorization but use a secret without the workers scope. Expect binding or use to fail.
• Remove caller authorization while keeping the correct secret scope. Expect failure. Both checks must pass.
• Force the upstream service to return an error containing sensitive text. Confirm the agent receives a generic error.
• Search Worker logs and traces for the test key. Confirm the value never appears.
• Rotate the provider key and verify the old key stops working.
• Disable one bot and confirm the other bot identities still work.
• Exceed the rate limit. Confirm the action stops and the event is recorded.
• Try an arbitrary upstream URL in the request body. Confirm the Worker ignores or rejects it.

Run these tests again after policy changes, new action types, and secret rotations. A boundary that worked six months ago may be bypassed by a new route added last week.

When a per-Worker secret is enough

Use a normal per-Worker secret when one Worker owns one credential, the value does not need reuse across supported integrations, and simple Worker deployment controls are enough. This is often the cleanest design for a small service.

Use Secrets Store plus a Worker or credential broker when an account-level reusable secret needs centralized lifecycle management, several supported bindings need the same value, or you need a policy layer across many agents and actions.

Do not confuse more parts with more security. A small Worker with one narrow secret can be safer than a complicated broker with broad permissions. Choose the fewest moving parts that maintain the required separation.

AI agent credentials checklist

• Keep reusable provider secrets out of agent prompts, tools, output, and local files.
• Give every agent a separate outer machine identity when separate revocation matters.
• Store account-level reusable values in Cloudflare Secrets Store only when its integration model fits.
• Use a per-Worker secret for a simple one-Worker boundary.
• Require both caller authorization and the correct secret scope.
• Remember that Read shows metadata only; Edit is required to bind.
• Bind each secret only to the Worker that needs it.
• Make the upstream provider credential as narrow as possible.
• Map agent requests to named actions, not arbitrary provider URLs.
• Return filtered results instead of raw keys.
• Use provider-issued short-lived credentials only when direct access is required.
• Treat signatures, nonces, allowlists, and five-minute lifetimes as custom controls.
• Rate limit by agent and action.
• Keep application action logs in addition to Secrets Store audit logs.
• Rehearse single-agent disable, provider rotation, and rollback.
• Keep production and development credentials separate.
• Never commit environment files or development variables.
• Review Cloudflare’s open beta limits and current documentation before launch.

Frequently asked questions

Is Cloudflare Secrets Store a password manager for AI agents?

No. It is an account-level store for encrypted, reusable secrets that connect to supported Cloudflare integrations. Your Worker or broker still decides what an AI agent may do and what result it receives.

Can a Worker read a bound value?

Yes. For a Secrets Store binding, Worker code uses an asynchronous call such as await env.BINDING.get(). Keep the result server-side and use it only for the approved upstream request.

Does Read access reveal secret values?

Cloudflare documents Read as metadata-only access. It does not reveal the stored secret value and cannot create a binding. Edit access is required to bind a secret to an integration.

Are Cloudflare Worker secrets the same as Secrets Store secrets?

No. A Worker secret is attached to an individual Worker deployment. Secrets Store provides reusable account-level secrets for supported integrations. The management and reuse boundaries differ.

Does Cloudflare Access replace a credential broker?

No. Access can identify and admit a machine to an application. The broker or Worker must still authorize the requested action, target, and limits.

Does Cloudflare Tunnel protect stored credentials?

Tunnel protects a transport path to an origin. It is not a secret vault, secret rotation service, or action authorization engine.

Does Secrets Store create short-lived credentials?

Not by itself. A custom broker or upstream provider can exchange a reusable key for a short-lived credential. Its lifetime and scope come from that system, not from Secrets Store.

What should the agent receive?

Prefer a filtered action result, such as a ticket summary or deployment status. If direct access is necessary, return an upstream-issued short-lived credential with the smallest possible scope. Never return the reusable store value.

What happens during secret rotation?

Update the stored value through the current supported workflow, test the bound Worker, revoke the old provider credential, and prove the old value fails. If an agent identity was compromised, revoke that identity separately.

Are audit logs enough for compliance?

No. Secrets Store audit logs and application logs provide evidence, but compliance also depends on retention, access review, incident processes, provider settings, and applicable rules. Get qualified advice for legal or regulatory decisions.

Official Cloudflare sources

• Cloudflare Secrets Store overview
• Secrets Store access control
• Secrets Store Workers integration
• Secrets Store audit logs
• Cloudflare Workers secrets
• Cloudflare Access service tokens
• Cloudflare Tunnel
• Secrets Store API reference

Build the boundary before the bots multiply

Good AI agent secrets management is not about hiding one giant key more carefully. It is about keeping reusable secrets in server-side storage, giving each caller a clear identity, authorizing one action at a time, and making rotation small enough to practice.

If you need help turning this pattern into a practical Worker and credential broker design, contact Building Better Software. We can map the trust boundaries, choose the simpler native or custom approach, and build failure tests before production access expands.

This guide reduces common risks but does not guarantee security. Your code, Cloudflare account controls, upstream provider permissions, agent runtime, and incident response process all remain part of the security boundary.