API Keys for AI Agents: Scoping, Metering, Rotation

Why agents break the classic API key model

A traditional API integration is deterministic. A developer writes code, the code makes a known set of calls, and the key sits in a server environment nobody reads. Every assumption in that model fails when the caller is an AI agent.

First, call patterns are nondeterministic. An agent told to "check the top holders of every large fund" can fan out into thousands of requests you never wrote. Arkolith's Q1 2026 13F dataset alone covers 1,824 institutional filers and 1.87 million long positions representing $53.7 trillion in reported value. An agent paging naively across that surface will happily spend whatever you let it spend.

Second, the context window is a leak surface classic applications do not have. Anything in a prompt can be echoed in output, logged in a transcript, replayed into another tool, or pasted into a bug report. Code does not gossip about its environment variables. Models, structurally, can.

Third, agents retry. A model that receives a rate-limit response or an ambiguous error will often try again, sometimes rephrased, sometimes in a tight loop. With a human, a mistake gets noticed in minutes. With an unattended agent, it gets noticed on the invoice.

The consequence: the key stops being a login and becomes the entire control surface, encoding who is calling, what they may touch, and how much they may spend. Platforms designed for agent callers (a theme in our comparison of market data APIs for AI agents) build the key model around this reality.

The absolute rule: keys never go in prompts

A prompt is not a secret store. Everything in an agent's context can end up somewhere you do not control: conversation logs, shared transcripts, debugging traces, downstream tools, or the model's own reply. If you type "my key is ak_live_..." into a chat, assume it has been copied somewhere durable. No attacker is required; ordinary logging is enough.

The correct place for a credential is the layer the model cannot read. For direct REST calls, that is an environment variable or a secret manager, injected at request time:

curl -H "Authorization: Bearer YOUR_KEY" "https://arkolith.com/api/v1/funds"

For agent frameworks, it is the tool configuration. This is one of the quiet advantages of the MCP architecture: the MCP client attaches the Authorization header itself, from its config file, on every tool call. The model sees tool names, arguments, and results. It never sees the credential, so it cannot leak what it never had. Our guide to connecting Claude to market data walks through the setup: the key lives in a JSON config block, never in a message.

Two corollaries follow. Do not put keys in system prompts or few-shot examples either; those are still context. And if a key has ever appeared in a transcript, even a private one, treat it as exposed and rotate it. Keys are cheap to replace. Auditing who might have read a log is not.

Scoping: mint the smallest key that works

The default failure mode is one god key shared across every script, notebook, and agent. It feels convenient until something misbehaves and the logs cannot tell you which caller did it.

Scoping for agents has two parts. The first is capability: a research agent reading filings data needs read access to the data plane and nothing else. On Arkolith, an API key authenticates the versioned data API (funds, holdings, insider filings, search) and does not grant access to billing or account settings; those stay behind interactive login. A leaked data key is a metered-read problem, not an account-takeover problem.

The second part is attribution. One key per agent means that when your usage log shows a burst of four thousand holdings calls at 3 a.m., you know exactly which loop to fix. Shared keys turn every anomaly into archaeology.

Minting a dedicated key takes a minute (see the quickstart), so there is no economy in sharing. Name keys after the agent and the project, and you get an audit trail for free.

Metering: a hard budget beats good intentions

Open-ended postpaid billing assumes the caller is a human who will notice a mistake. An agent in a retry loop will not notice anything. Prepaid, metered credits invert the risk: the worst case is a drained balance and a stopped agent, not a surprise bill. For unattended workloads, that bounded failure mode is the most valuable property a billing model can have.

Metering works best when calls are weighted by what they cost to serve: a lightweight entity search should price differently from pulling a fund's full holdings history, which keeps spend proportional to work and budgets predictable.

Metering also rewards knowing the data's natural cadence. SEC ownership data does not change continuously. 13F filings land up to 45 days after each quarter end (February 17, May 15, August 14, and November 16 in 2026; the SEC's Form 13F FAQ covers the mechanics), while Form 4 insider filings arrive within 2 business days of the trade. An agent polling 13F holdings hourly is burning credits on data that updates quarterly; the 51,000+ insider transactions Arkolith tracks turn over far faster and justify tighter polling. Cache the slow streams, poll the fast ones, and budget around the filing calendar.

# Light call: resolve the entity first
curl -H "Authorization: Bearer YOUR_KEY" "https://arkolith.com/api/v1/search?q=berkshire"

# Heavier call: full holdings for one CIK. Fetch once, cache until the next deadline
curl -H "Authorization: Bearer YOUR_KEY" "https://arkolith.com/api/v1/funds/0001067983/holdings"

Rotation and revocation: assume exposure, make it cheap

Rotation has two triggers: the clock and the event. Scheduled rotation (quarterly is a reasonable default for read-only data workloads) bounds the lifetime of any silent compromise. Event-driven rotation is non-negotiable: rotate the moment a key appears in a transcript, screenshot, committed file, or error message, even if you believe nobody saw it. The cost asymmetry is extreme. Rotating takes a minute; proving a leaked key was never used takes forever.

The practices above make rotation cheap. If every agent has its own key stored in exactly one config location, rotation is mechanical: mint the replacement, swap the config, revoke the old key. If one key is buried in five notebooks, two cron jobs, and a teammate's shell profile, you will postpone rotation, and postponed rotation is no rotation.

Revocation should be instant and independent of rotation. When an agent misbehaves (a runaway loop, signs of prompt injection, calls that do not match its task), killing its key is the fastest circuit breaker you have. And as covered in MCP vs REST API, both transports ride the same credential, so one revocation severs both paths.

A scoped, metered key controls what an agent can spend, not what it can claim. Pair key hygiene with per-datapoint provenance, so when the agent reports a position, the claim traces to a specific SEC accession number you can verify on EDGAR full-text search. We cover that half of the problem in stopping AI from hallucinating market data.

A sane end-to-end setup for one agent

A checklist that takes about ten minutes:

1. Mint a dedicated key named for the agent and project. Never reuse a human's key.
2. Store it once: environment variable for scripts, client config for MCP. Confirm it appears in no prompt, system prompt, or example.
3. Fund a prepaid budget sized to the workload, small at first; top up after a week of real usage rather than guessing.
4. Set the agent's polling cadence to the data's cadence: quarterly streams get cached, the insider feed gets polled.
5. Review the first week of per-key usage logs; nondeterministic callers develop habits you cannot predict from the prompt.
6. Calendar a quarterly rotation; rotate immediately on any exposure.

None of this is exotic. It is ordinary least-privilege security adapted to a caller that is fast, tireless, and occasionally wrong about what you asked for. The API documentation covers key management and per-call pricing in detail.

Frequently asked questions about API keys for AI agents

Is it ever safe to paste an API key into a chat with an AI assistant?

No. Conversation context gets logged, replayed, and echoed in ways you cannot audit, so any key that enters a prompt should be treated as exposed. Put the key in the MCP client config or an environment variable instead, and if you have already pasted one, rotate it now.

How often should I rotate API keys used by AI agents?

Use two triggers: a calendar schedule (quarterly is a sensible default for read-only data access) and an immediate rotation on any exposure event, such as a key appearing in a transcript or a committed file. Per-agent keys stored in a single config location make rotation a two-minute task.

What is the difference between scoping and metering?

Scoping limits what a key can do: which endpoints, which data, read versus write. Metering limits how much it can do: call volume and spend, ideally against a prepaid balance. You need both, because scoping caps the blast radius in kind while metering caps it in quantity.

Do MCP servers see my API key, and does the model?

The MCP client sends your key as an Authorization header on each request, so the server receives it to authenticate and meter the call, exactly like any REST API would. The model itself never sees the credential; it only sees tool names, arguments, and results. That separation is the core security advantage of client-layer key configuration.

This article explains public filings and data concepts. It is not investment advice.