Scoped API permissions: what the check tests and how to fix it

Weight 1.5. Scans portal and key docs for scope names like read:items, 'scope' near token or access, and wording like restricted keys or read-only.

Agent Auth · Weight 1.5 in the w2agent Score

How common is it?

3% of 638 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

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: or update: followed by a word, such as read:orders.

  • Each occurrence of scope with permission, token or access within 200 characters.

  • Lines that begin with - or * followed by a word:word pair. 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:orders and write:orders. OAuth accepts any scope names; this check only recognises the verb-first form with read, write, admin, delete or update, so orders:read is 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_supported for the basic set. Your docs and that field should agree. See OAuth discovery.
  • Return the required scope in the WWW-Authenticate challenge so a client can ask for just that scope.

Credentials and rate limits are covered by agent auth docs.

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 →