Authentication Requirements Extraction Prompt

Security engineers and API documentation teams face a persistent challenge: keeping per-endpoint authentication requirements accurate and synchronized with the live API contract. An OpenAPI spec may declare security schemes at the top level, but individual endpoints often override, extend, or omit those schemes. Implementation code adds another layer of truth with middleware annotations, scope checks, and conditional auth logic that specs alone cannot capture. This prompt extracts authentication requirements from OpenAPI security scheme objects, source code annotations, or both, producing a structured per-endpoint auth table that includes method type, token format, required scopes, OAuth flow details, and consistency warnings against actual auth middleware.

Use this prompt when you need to generate or audit authentication documentation that must match the real behavior of your API, not just the spec file. It is appropriate when your API has multiple authentication methods across endpoints, when OAuth scopes vary by operation, when middleware enforces rules that differ from what the spec declares, or when you are preparing for a security audit that requires per-endpoint auth traceability. The prompt works best when you can provide both the OpenAPI specification and relevant source code files containing auth middleware, decorators, or annotations. If you only have a spec file without implementation access, the prompt will still produce useful output but will flag gaps where code-level verification is impossible.

Do not use this prompt for APIs with a single, uniform authentication method applied globally without endpoint-level overrides—a simple paragraph in your docs will suffice. Avoid it when your auth logic is entirely external, such as when an API gateway handles all authentication before requests reach your service and no per-endpoint differentiation exists in code or spec. This prompt is also overkill for internal tools with no auth requirements or for documentation drafts where approximate auth descriptions are acceptable. For those cases, a manual summary or a simpler template will be faster and less prone to false precision. If your goal is to document OAuth provider configuration, token endpoint details, or user-facing login flows rather than per-endpoint requirements, use a dedicated authentication overview prompt instead.

Before running this prompt, gather your OpenAPI spec file and identify the source files containing auth middleware, route decorators, or security annotations. If your codebase uses a framework like FastAPI, Express, Spring Security, or Django REST Framework, point the prompt at the specific files where @requires_auth, @scope, security=[...], or equivalent constructs appear. The prompt's value scales with the complexity of your auth surface—APIs with ten endpoints and two scopes may not justify the extraction effort, while APIs with hundreds of endpoints, multiple OAuth flows, and scope matrices will benefit significantly. After extraction, always validate the output against a sample of actual API calls with different credential types to confirm the documented requirements match runtime behavior.

This prompt template extracts authentication and authorization requirements from OpenAPI security schemes, source code annotations, or middleware configurations. It produces a structured table mapping each endpoint to its required auth method, token type, OAuth scopes, and any conditional access rules. Use this when you need to generate or audit authentication documentation that stays synchronized with the actual security implementation.

codeCopy
You are an authentication documentation extractor. Your task is to analyze the provided API specification or implementation code and produce a structured inventory of authentication requirements for every endpoint.

## INPUT
[OPENAPI_SPEC_OR_CODE]

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "api_title": "string",
  "auth_methods_defined": [
    {
      "scheme_name": "string",
      "type": "http | apiKey | oauth2 | openIdConnect | mutualTls | custom",
      "description": "string",
      "scheme_details": {
        "scheme": "bearer | basic | digest | other",
        "bearerFormat": "JWT | opaque | other | null",
        "in": "header | query | cookie | null",
        "name": "string | null"
      },
      "oauth_flows": {
        "flow_type": "implicit | password | clientCredentials | authorizationCode | null",
        "authorizationUrl": "string | null",
        "tokenUrl": "string | null",
        "refreshUrl": "string | null",
        "scopes": {
          "scope_name": "scope_description"
        }
      } | null
    }
  ],
  "global_security_requirements": [
    {
      "scheme_name": "string",
      "scopes": ["string"]
    }
  ],
  "endpoint_auth": [
    {
      "path": "string",
      "method": "GET | POST | PUT | PATCH | DELETE | HEAD | OPTIONS",
      "summary": "string",
      "operationId": "string | null",
      "security_requirements": [
        {
          "scheme_name": "string",
          "scopes": ["string"],
          "scope_descriptions": {
            "scope_name": "scope_description"
          }
        }
      ],
      "overrides_global": true | false,
      "auth_optional": true | false,
      "notes": "string | null"
    }
  ],
  "inconsistencies": [
    {
      "severity": "error | warning | info",
      "path": "string | null",
      "method": "string | null",
      "description": "string",
      "recommendation": "string"
    }
  ],
  "extraction_confidence": "high | medium | low",
  "extraction_notes": "string"
}

## CONSTRAINTS
- Extract every endpoint path and method combination present in the input.
- If an endpoint has no explicit security requirement, check whether it inherits global security or is intentionally unauthenticated. Flag both cases explicitly.
- For OAuth2 flows, enumerate every scope defined in the spec, not just scopes referenced by endpoints.
- If the input is implementation code rather than an OpenAPI spec, infer auth requirements from middleware annotations, decorators, guard clauses, or configuration files.
- Flag as inconsistencies: endpoints with no security definition when global security exists, scopes referenced by endpoints but not defined in the scheme, schemes referenced but not defined, and endpoints that appear to require multiple conflicting auth methods.
- Set extraction_confidence to "low" if the input is ambiguous about auth requirements, and explain why in extraction_notes.
- Do not invent auth methods, scopes, or requirements not present in the input.

## EXAMPLES
[OPTIONAL_FEW_SHOT_EXAMPLES]

## RISK LEVEL
[RISK_LEVEL: standard | high]

If RISK_LEVEL is "high", include an additional field "requires_human_review": true in the output and flag every inferred or ambiguous auth requirement for manual verification.

After pasting this template, replace [OPENAPI_SPEC_OR_CODE] with your actual OpenAPI JSON/YAML or relevant code sections. If you have few-shot examples of correctly extracted auth tables from your own API surface, add them to [OPTIONAL_FEW_SHOT_EXAMPLES] to improve consistency with your team's documentation style. Set [RISK_LEVEL] to "high" when documenting authentication for production APIs that handle sensitive data, payment methods, or personally identifiable information—this forces the model to flag every inference for human review. Before wiring this into an automated pipeline, validate the output against your actual auth middleware configuration to catch extraction errors early.

This prompt is designed to be integrated into an automated documentation pipeline, not used as a one-off manual query. The primary integration point is a CI/CD step that runs after OpenAPI spec changes or auth middleware updates. When a pull request modifies securitySchemes, security blocks, or authentication middleware files, the pipeline should trigger this prompt to regenerate the per-endpoint auth tables. The prompt expects a structured [INPUT] containing the OpenAPI fragment or code annotations, and it returns a machine-readable [OUTPUT_SCHEMA] that can be validated before merging into your docs site or developer portal.

The implementation harness should enforce a strict validation layer before accepting the model's output. After the prompt returns, run a schema validator against the expected JSON structure: each endpoint must have a non-empty auth_methods array, each method must include type, scopes, token_lifetime, and oauth_flow fields where applicable. Add a consistency check that compares the extracted auth requirements against the actual auth middleware configuration—flag any endpoint that the prompt claims requires a Bearer token but the middleware allows unauthenticated access. For high-risk APIs (auth, payments, user data), require a human approval step in the pipeline: the generated auth tables are staged as a PR comment, and a security engineer must approve before the docs are published. Log every prompt run with the input spec version, output hash, validation results, and reviewer identity for audit trails.

Choose a model with strong structured output support and low hallucination rates on technical specification tasks. GPT-4o or Claude 3.5 Sonnet with strict JSON mode enabled are appropriate defaults. Set temperature to 0 or near-zero to maximize consistency across runs. Implement a retry strategy: if validation fails, retry up to two times with the validation errors appended to the [CONSTRAINTS] field. If the output still fails after retries, escalate to a human reviewer and block the docs merge. Do not use this prompt for real-time auth checks or as a substitute for actual security enforcement—it documents what the spec claims, not what the running system enforces. Pair this prompt with the API Contract Drift Detection Prompt to catch discrepancies between documented auth and live behavior.