Agent Policy vs API Keys and Authentication
Published November 14, 2026 · Reviewed November 2026 · By the Ingenious AI team
The short answer
An agent policy and an API key do opposite halves of the access problem. The policy declares — publicly, in advance, to everyone — what an agent may do on your site. Authentication verifies — privately, per request — who is asking, and keys meter and control what a verified caller may do. AGENT-POLICY v0.1 is explicit that authentication is outside its scope: the file identifies agents by name for the purpose of terms, and proves nothing about anyone.
What is the difference between declaring and authenticating?
Declaration answers "what are the rules here?" Authentication answers "who are you, and are you allowed through this door?" A public website needs the first answer published where strangers can fetch it — its whole value is being readable before any relationship exists. An API needs the second answer enforced per request, because its operations change state and consume resources. Confusing the layers produces the two classic errors: expecting a policy file to keep anyone out (it cannot — it is a notice), and expecting an API's key regime to communicate terms to the open web (it cannot — it speaks only to keyholders). Policy vs bot blocking draws the same line from the enforcement side.
What the identifier is — and is not
The policy's identifier field looks like identity and is not. openai/agent in a rule names the class of agent the rule addresses, the way a sign names the guests a rate applies to. Nothing checks that a given request actually comes from that agent — the spec lists authentication of agents and of publishers among v0.1's deliberate omissions, beside the signature placeholder that reserves the publisher half for a future version. This is not a flaw awaiting a patch; it is the format's scope decision. Public terms are a pre-relationship instrument. The moment a relationship exists — a partner, a paid tier, transactional rights — identity and keys enter, through your own systems, and the policy's role narrows to what it does uniquely: stating the terms those systems implement.
How the layers compose in a real stack
Picture the layers in the order an agent meets them. Discovery: the agent fetches your policy and learns the terms — including that api-call is disallowed for the public, or permitted for named partners. Relationship: a partner negotiates, signs whatever your business requires, and receives credentials through your ordinary channels. Enforcement: your API gateway authenticates the key, applies rate limits mechanically (the enforced twin of the policy's declared rate_limit), and logs usage against the relationship. Record: the policy file, updated with the partner's named rule, remains the public statement of the arrangement's existence and shape. Each layer does one job; the architecture works because none of them impersonates another. AgentGate's own tiers mirror the split — the pricing page sells policy tooling and hosting, never identity services.
The api-call verb is where they meet
Of the twelve suggested actions, api-call is where declaration and authentication most visibly intersect. A policy can permit it, refuse it, or hold it at conditional — and each choice is a statement about your API's public posture. Most sites refuse it for the world (an unauthenticated invitation makes no sense) and permit it inside named rules for partners whose keys exist elsewhere. The policy then functions as the API's public annex: discoverable terms for a door that itself requires credentials. SaaS owners will find the pattern worked end-to-end in the SaaS guide — the file declares, the gateway verifies, and neither apologises for the other.
Worked example: a data API layers policy over keys without confusing them
Fictional example. Tidepool Data, a fictional marine-weather API serving 1,300 developer customers, publishes a policy whose catch-all disallows api-call outright, while 6 named partner rules permit it — each rule restating, in its data-use terms, that access runs under the partner's issued credentials and published fair-use caps. The API gateway enforces keys and a mechanical 300-requests-per-minute ceiling; the policy's declared partner cap of 240 sits deliberately beneath it, so the public terms promise less than the machinery allows. When a seventh integration asked how to begin, the answer was two links: the policy (the terms) and the developer signup (the keys) — in that order, because terms precede credentials in every healthy integration Tidepool runs.
The declaration-vs-authentication checklist
- Publish terms openly. The policy is for strangers: no keys, no login, fetchable by anyone deciding whether to approach you.
- Never treat identifiers as identity. A rule names who terms are for; it verifies nobody. Design nothing on the assumption that it does.
- Put enforcement in the gateway. Keys, mechanical rate limits, and metering live in your API infrastructure, where they can actually act.
- Let named rules describe keyed relationships. A partner's rule states the arrangement's public shape; the credentials themselves never appear in the file.
- Keep the numbers coherent. Declared caps and enforced caps should tell one story — promise publicly at or inside what the machinery enforces.
Keep reading
Agent Policy for Online Stores: a Practical Pattern · Agent Policy for Banks and Finance Sites · How to Tell AI Agents What They May Do · Spec samples · Conformance · Pricing · All guides
Frequently asked questions
Can an agent prove it is the agent my rule names?
Not within v0.1. The format does no authentication of agents — the identifier is a name a rule addresses, not a credential a request presents. Where proof matters, it comes from your own relationship machinery: accounts, keys, signed agreements. The policy states terms for the named agent; your systems decide who qualifies as that agent.
Does the policy's signature field authenticate my site?
Not yet. signature is a required field whose v0.1 value is null — a placeholder for a future signature profile (the roadmap names a JWS detached signature) that would let agents verify authorship. Today, authorship assurance is the mundane kind: the file is served from your origin, over HTTPS, at the well-known path.
Should API keys be mentioned in the policy file?
Their existence, yes — a named rule can state that api-call access runs under issued credentials. The keys themselves, never: the policy is a public document fetched by strangers, and credentials in it would be credentials published. The file describes the door; it must never contain what opens it.
My API already has keys and docs. Why add a policy?
Because your docs speak to developers who already found you, while the policy speaks to agents deciding whether to operate on your whole site — pages, catalogue, and API together — in one fetch, in a format they parse natively. The policy is the discoverable front door for agent terms; the API programme remains the house behind it.
Can the policy's rate_limit replace my gateway's throttling?
No. The declared limit is a term — a promise and an expectation, useful for planning and for the record when it is breached. Mechanical throttling is what actually protects the service at 3 a.m. Mature setups run both, with the declared number at or inside the enforced one, so the public promise is never the first thing to break.
Generate a policy — free · Validate a policy · What an agent access policy is