Agent and bot auth documentation: what the check tests and how to fix it

Weight 2. Counts API key, OAuth or rate limit mentions near agent, bot, token, scope or permission wording in portal, key docs and homepage text.

Agent Auth · Weight 2 in the w2agent Score

How common is it?

18% of 671 measured sites where this check applied pass.

Latest audit of each site under rubric v3.1. Sites where the check did not apply or could not be measured (for example, no llms.txt for the llms.txt checks) are left out. A partial result does not count as a pass.

What this check tests

This is a text-pattern check, not an understanding of your documentation. It builds one block of text from up to three places:

  • the developer portal page the developer portal check found, if any;
  • a key-docs page at /keys, /api-keys or /docs/keys on your origin (any 2xx answer, not only HTML; the origin paths are skipped on catch-all sites), or the same paths on the docs. subdomain;
  • your homepage text.

In that text it finds every occurrence of api key, oauth or rate limit. An occurrence counts as one signal when the 200 characters before and after it contain any of agent, bot, ai, scope, permission or token. These are substring matches, not whole words, so ai is also found inside words such as "details", "available" or "email", and bot inside "both". In practice, any prose that mentions API keys, OAuth or rate limits and runs on for a few sentences will often count.

  • Pass 100: three or more signals.
  • Partial 50: one or two.
  • Fail 0: none.
  • Skip: no developer portal was found and the audit could not reach anything to probe. A fail is also changed to skip when the portal check failed or was skipped; a pass or partial is kept. So a site with no developer portal can still show a result here if its homepage or key-docs page mentions these terms.

Why it matters to agents

An agent that finds your API still has to know how to get credentials, what scopes exist, and what limits apply. OAuth defines the scope parameter as a list of strings that the authorization server defines (RFC 6749, section 3.3), so the meaning of each scope is only discoverable if you write it down. RFC 9728 gives protected resources fields for this: resource_documentation points to developer information and resource_policy_uri to the requirements on how data may be used. The MCP authorization specification asks servers to signal required scopes in the WWW-Authenticate challenge and scopes_supported, so clients request the minimum they need.

Be realistic about the check. It cannot judge whether the documentation is correct or whether it addresses automated clients. A page can pass without telling agents anything useful, and good documentation phrased differently can fail.

If you have no API, there is nothing to document and the check is usually skipped.

How to fix it

Write the page for a developer building an agent, then phrase it so the terms appear together:

  • How to get credentials: where a key or OAuth client is created, and whether an automated client is allowed to do this without a person.
  • Rate limits: the numbers, the response status and headers when exceeded, and how an agent should back off.
  • Scopes: each scope name, what it allows, and which operations need it.
  • Token handling: lifetime, refresh, and how an agent should treat a 401 or 403.
  • Acceptable use for bots and agents, in one short section.

Publish it at /developers, /keys or on docs. where the audit looks, and link it from protected resource metadata as resource_documentation (see OAuth discovery). Detail on the scope vocabulary is checked separately by scoped permissions.

Examples from measured sites

Up to 10 of the highest-scoring sites in each group, from recent audits. Failing includes partial results.

Passing

Failing or partial

Sources

Verified against these sources on

Does your site pass this check?

Check your own site →