What this check tests
The audit reads text, not your OAuth configuration. The text is the developer portal page found by the developer portal check plus a key-docs page (/keys, /api-keys or /docs/keys, on your origin or on docs.). Your homepage, your OpenAPI file and your authorization server's scopes_supported are not read.
It adds up four kinds of signal:
-
Each occurrence of a lowercase
read:,write:,admin:,delete:orupdate:followed by a word, such asread:orders. -
Each occurrence of
scopewithpermission,tokenoraccesswithin 200 characters. -
Lines that begin with
-or*followed by aword:wordpair. The audit collapses all whitespace before matching, so this pattern effectively cannot match in practice. -
One signal for each of four phrases that appear anywhere: restricted API keys; read-only or read and write; custom, limited, scoped, restricted or granular permissions; limit or limited access.
-
Pass 100: a total of three or more.
-
Partial 50: one or two.
-
Fail 0: none, or there was no portal or key-docs text to scan.
-
Skip: the audit could not reach the portal at all. A fail is also changed to skip when the portal check failed or was skipped; a pass or partial is kept.
Why it matters to agents
When an agent acts for a person, the safe default is the smallest set of permissions that does the job. RFC 9700 says access token privileges "SHOULD be restricted to the minimum required for the particular application or use case", which reduces damage if a token leaks. The scope parameter is the OAuth mechanism for that (RFC 6749, section 3.3), and the strings are defined by your authorization server, so an agent can only choose them wisely if you document them. MCP clients are told to request only the scopes necessary, starting from the scope in your WWW-Authenticate challenge or scopes_supported.
The check measures whether scope-like language appears in your docs. It does not test that your API enforces scopes, and a page of marketing wording such as "granular permissions" can raise the count. Treat a pass as a prompt to read your own documentation, not as proof of least-privilege design.
If you have no developer portal or API, the check is normally skipped.
How to fix it
- Define narrow scopes per resource and action, for example
read:ordersandwrite:orders. OAuth accepts any scope names; this check only recognises the verb-first form withread,write,admin,deleteorupdate, soorders:readis valid but does not count. - Document every scope in one list on the portal or key-docs page: name, what it allows, which endpoints need it.
- Offer read-only or restricted keys for automation, and say so in plain words ("restricted API keys", "read-only").
- Where you publish authorization server metadata, include
scopes_supportedfor the basic set. Your docs and that field should agree. See OAuth discovery. - Return the required scope in the
WWW-Authenticatechallenge so a client can ask for just that scope.
Credentials and rate limits are covered by agent auth docs.