API Auth Transparency

What this parameter measures

Does your API make its authentication method clear to an agent? This parameter checks for that. friendly4AI inspects two sources: a prefetched OpenAPI spec, where it reads components.securitySchemes for named schemes, and the homepage HTML, where it scans for strong auth hints (api-key, x-api-key, Authorization: Bearer, bearer token, oauth2, client id, client secret, securitySchemes, Basic auth) and weaker generic hints (authentication, authorize, access token, api docs, rest api). A named security scheme in the spec or any strong hint in the HTML is treated as explicit transparency.

Why it matters for AI-readiness

An agent cannot call a protected endpoint unless it knows how to authenticate. When your spec declares securitySchemes (OAuth2 flows, an API key header, or bearer tokens) and your docs explain how to obtain and use credentials, an AI tool can complete the auth handshake on the user's behalf. Vague or missing auth information stops automation cold: the agent can see the endpoint but has no way in. Transparent, machine-readable auth is the difference between a documented API and a usable one.

How we score it

This is a gradient AI-Specific Signals parameter, and the scanner refines the rubric into three tiers. It passes (100) when the spec defines any securitySchemes or the HTML carries an explicit scheme hint. It scores partial (50) when only generic authentication language appears without a named scheme. It fails (0) when neither the spec nor the HTML reveals any auth information. This parameter is API-conditional: its weighted contribution counts only when an API is detected on the site (via api-discoverability); otherwise its effective weight is zero and it is excluded from the score, so sites without an API are not marked down for undeclared auth.

How to fix common issues

• Declare your authentication in the OpenAPI spec under components.securitySchemes (for example oauth2, apiKey, or http bearer).
• Name the scheme explicitly in your developer docs — Authorization: Bearer, X-API-Key, or an OAuth2 flow — rather than only saying "authentication required."
• Document how to obtain credentials, authenticate a request, and refresh tokens, with a complete example.
• Reference the auth scheme on a getting-started page so the strong hints are discoverable in the HTML.
• Re-scan after documenting auth to confirm an explicit scheme is detected.