Managing API Keys and Secrets for AI Agents: Storage and Rotation

Managing API Keys and Secrets for AI Agents: Storage and Rotation

Managing API keys and secrets for AI agents comes down to one rule: keep every key in a secrets vault, hand it only to the code that runs the tool, and never put it in the prompt, the model context or the logs. Each credential should have the smallest possible scope, belong to a single agent and environment, and be replaceable without stopping operations. The model decides which action to request. The execution layer holds the key.

Key takeaways

• The model never receives the key. It requests an action, and a trusted execution layer attaches the credential.
• A secrets vault, or variables injected at runtime, replaces files, repositories, spreadsheets and chat messages.
• One key per agent, per integration and per environment, with minimum permissions and, at first, read-only access wherever possible.
• Rotate with an overlap period: create the new key, validate it, switch over, revoke the old one and record everything.
• Rotate immediately when a leak is suspected, when someone with access leaves, or when the agent's scope changes.

Why should the model never see the key?

Anything that enters a language model's context can, in principle, come back out. If the key sits in the system prompt, in a retrieved document or in a tool result, it can show up in a reply, in a conversation log or in a call an attacker managed to induce. Prompt injection makes this concrete: malicious text inside an email, a PDF or a WhatsApp message can ask the agent to repeat its instructions or send data elsewhere. The OWASP guidance on preventing prompt injection and the OWASP Top 10 for LLM applications cover this class of risk, including disclosure of sensitive information.

The design rule is simple: what the model cannot see, it cannot leak. Instead of asking the model to build a request with an authorization header, the model returns a structured intent, for example a look-up-order action with an order number. Deterministic code validates the parameters, fetches the credential from the vault, makes the call and returns only the necessary result to the model. This separation is the same principle behind function calling: the model chooses the tool, and the system executes it.

This applies to any architecture, whether an n8n workflow, a custom agent or a coding assistant. In developer tools, the same care shows up in permissions, sandboxing and secrets, the subject of the article on Claude Code security for teams.

Where should API keys be stored, from worst to best?

Most leaks do not come from a sophisticated attack. They come from a key forgotten in a convenient place. Use this list as a decision guide, starting with the places that should be eliminated.

• Prompts, agent instructions or memory files: never. This is the worst place, because it puts the key in front of the model.
• Code repositories, even private ones, and versioned configuration files: avoid. History keeps the key forever, and repositories get cloned and shared.
• Spreadsheets, shared documents, chat messages and email: forbidden. These are the most common channels for informal credential sharing.
• Exported automation workflows: be careful. When you export a flow from an automation platform, check whether the credential was embedded in the file or only referenced.
• Environment variables injected at execution time: acceptable as a minimum, as long as the environment is restricted and the variables are not printed in logs or diagnostic screens.
• A managed secrets vault (your cloud provider's or a dedicated tool): the recommended destination. It offers access control, an audit trail and centralized rotation.

If the company does not have a vault yet, the first step does not need to be sophisticated. Pick the secrets feature of the provider that already hosts the application, restrict who can read it and start there. What matters is a single source of truth with a named owner.

How do you limit the scope of each credential?

Storing a key well is not enough if the key can do everything. If it leaks, the damage is proportional to what it allows. The principle of least privilege, described in the OWASP authorization guidance, shapes this decision: grant only what the task requires and nothing more.

In practice, apply these rules to every agent integration:

• One key per agent. If two agents share a credential, you cannot tell which one acted, and you cannot revoke one without taking down the other.
• One key per environment. Test and production never use the same credential, and the test environment points to fictional data.
• Read permission first. An agent that checks order status does not need permission to cancel or refund.
• Narrow OAuth scopes. When the API offers OAuth, request only the scopes you need. Google's OAuth 2.0 documentation shows how scopes limit what an authorized token can access.
• Usage and spending limits when the provider allows them, so a compromised key cannot generate unlimited consumption.
• Origin restrictions, such as an IP allowlist, when the API supports them.
• Short-lived tokens instead of permanent keys whenever the integration supports them.

Systems such as ERPs and CRMs usually have their own permission profiles. Before connecting an agent to them, create a service user with a restricted profile instead of reusing an administrator's key. The risks of each path are covered in the guides on integrating AI with Bling, Omie or Tiny and on integrating AI with your CRM.

How do you rotate keys without taking the agent down?

Rotating means replacing one credential with another and invalidating the previous one. The operational risk is in the middle: if you revoke the old key before the agent uses the new one, operations stop. That is why safe rotation uses an overlap period, in which both keys work for a short interval.

A step-by-step plan that fits most cases:

• Identify the credential's owner and every place that uses it: agents, workflows, scripts, environments. If you do not know where it is used, the rotation will break something.
• Create the new key at the provider, with the same minimum scope as the previous one, and never with extra permissions for convenience.
• Store the new key in the vault as a new version, without deleting the old one yet.
• Make the agent read the new version. Ideally the execution layer fetches the secret from the vault at each start or at short intervals, instead of having the value fixed in code.
• Validate with a low-risk call, such as a read query, and confirm in the logs that the new key is in use.
• Revoke the old key at the provider.
• Record the date, the reason and the person responsible for the change, without recording the key value.
• Confirm that no authentication errors appeared in the following hours.

Also define when to rotate. There are two triggers. The first is periodic rotation, on an interval the company sets according to the sensitivity of the integration. The second is event-based rotation: a suspected leak, someone with access leaving, the end of a vendor relationship, a change in what the agent can do, or a provider alert. Event-based rotation should be rehearsed before an incident happens, because on the day of an emergency nobody wants to discover that the key is spread across five workflows.

How do you stop keys from leaking through logs, tools and prompts?

Even with a vault and tight scope, a key can escape through side channels. Review these points before putting the agent into production:

• Logs: never record authorization headers, request bodies containing credentials or full environment variables. Apply automatic masking to known fields.
• Error messages: an API error can echo the entire request. Clean the response before sending it back to the model or the user.
• Tool results: return only the necessary fields to the model. A tool that returns an account's full configuration may include secrets.
• MCP servers and third-party extensions: they run with whatever access you give them. Assess what each one reads before installing, as described in the guide on how to audit an MCP server.
• Detection: use automated secret scanning in the repository and in pipelines, to catch human error before it reaches the environment.
• Validation layer: check what the agent is about to send out. The practices of input, output and action guardrails help block a reply that contains something resembling a credential.
• Gateways and admin panels: if you use an agent platform with a dashboard, treat access to it as access to the keys. The OpenClaw Gateway security checklist shows the kind of evidence to require before exposing anything.

Illustrative scenario: an order agent on WhatsApp

Imagine, as a hypothetical example, a small restaurant group with a WhatsApp agent that answers menu questions and checks order status in a management system. This scenario is illustrative and does not describe a real case.

In the first design, someone pasted the management system's key, an administrator key, into the agent's instructions so it could build the calls on its own. Any customer who managed to convince the agent to repeat its instructions would get that key, with full permissions.

In the corrected design, the agent knows only two tools: check order status and look up the menu. An execution layer receives the model's request, validates that the order number has the expected format, reads from the vault a key belonging to a service user with read-only access to orders, and makes the call. The model receives only the status. The test key is a different one, and the production key is rotated through a written procedure with overlap. If a customer tries to extract the configuration, there is nothing to extract. For the conversation flow itself, see the article on AI for restaurants on WhatsApp.

How the map, limit, pilot and hand over method applies

Work on credentials follows the same method as any agent project. In map, we list every integration, who owns it, where the key lives today and which actions the agent genuinely needs to perform. In limit, we define minimum scope, one key per agent and environment, and what the model may or may not see. In pilot, we run a real flow with logs and test rotation during the pilot, including emergency rotation, against an agreed success metric. In hand over, we deliver the rotation procedure, the key inventory and the owners, so operations continue without depending on whoever built it. The final decision is to expand, adjust or stop.

The data that passes through these integrations matters too. If the agent touches customers' personal data, protecting the credentials is part of the security measures the company must be able to demonstrate. The article on LGPD and artificial intelligence covers that side in detail.

Frequently asked questions

Can I put the API key in the prompt if the agent is internal? It is not recommended. An internal agent also processes text we do not control, such as emails, attachments and web pages, and that text can induce the model to repeat what is in its context. Keep the key in the execution layer and give the model only the results of actions.

How often should I rotate an agent's keys? There is no universal interval. Set a periodic schedule proportional to what the key allows and the sensitivity of the data, and add event-based triggers such as a suspected leak, someone with access leaving or a vendor change. The most important thing is that rotation is a rehearsed procedure and not an improvisation.

Are environment variables enough, or do I need a secrets vault? Environment variables injected at runtime are an acceptable minimum to start with, as long as access to the environment is restricted and nothing prints them in logs. A vault adds access control, usage history and centralized rotation, and it becomes worth it as soon as you have more than one agent or more than one integration.

What should I do if a key leaks? Revoke the key at the provider immediately and create a new one with minimum scope, even if that causes a short pause in operations. Then review the provider's logs to see what was accessed in the meantime, record the incident and find out which channel the leak came through so you can close it. If personal data is involved, work with the company's data protection lead to decide what steps are required.

Sources

• OWASP: prevenção de injeção de prompt
• OWASP Top 10 para aplicações com LLM
• OWASP: guia de autorização
• Google: autorização OAuth 2.0