Scope-per-Endpoint Mapping Table Generation Prompt

This prompt is for API designers, security engineers, and platform product managers who need to produce a definitive, auditable scope-per-endpoint mapping table for an existing or planned API. The primary job is to turn an OpenAPI specification, internal API design document, or enumerated endpoint list into a structured reference matrix that maps every operation to its required OAuth scopes, documents the granularity rationale, and provides least-privilege examples. The output serves as the source of truth for permission documentation, IAM policy authoring, and security review.

Use this prompt when you have a complete or near-complete endpoint inventory and a defined scope model. The prompt works best with structured inputs: an OpenAPI spec, a markdown table of endpoints, or a well-organized API design doc. It expects you to supply the scope taxonomy and any business logic rules that govern scope assignment (e.g., 'read scopes are always required alongside write scopes for the same resource'). Do not use this prompt for a single endpoint or a handful of operations—it is designed for system-wide mapping. Do not use it if your scope model is still undefined or if you lack endpoint-level detail; the prompt will hallucinate plausible but incorrect mappings rather than flagging missing information.

The output is a structured table, not prose documentation. Each row must contain the HTTP method, path, operation ID, required scopes, an optional granularity rationale, and a least-privilege example. The prompt includes validation logic to flag undocumented endpoints present in the spec but missing from the mapping, and over-scoped permissions where a broad scope is assigned when a narrower one exists. After generating the table, you should run the built-in completeness checks, then route the output for human review by the security architecture team before publishing it as permission reference docs.

This prompt template generates a permission matrix that maps every API endpoint to its required OAuth scopes. It is designed for API designers and security engineers who need to produce unambiguous reference documentation for consumers. The template forces the model to reason about granularity decisions, flag undocumented endpoints, and identify over-scoped permissions before producing the final table.

textCopy
You are an API security documentation specialist. Your task is to produce a complete scope-per-endpoint mapping table for the API described below.

## INPUT
API Specification or Endpoint List:
[API_SPEC]

Current Scope Definitions (if any):
[SCOPE_DEFINITIONS]

## OUTPUT_SCHEMA
Return a JSON object with the following structure:
{
  "scope_definitions": [
    {
      "scope": "string (e.g., 'read:users')",
      "description": "string",
      "granularity_rationale": "string (why this scope exists at this level of granularity)"
    }
  ],
  "endpoint_mappings": [
    {
      "method": "GET|POST|PUT|PATCH|DELETE",
      "path": "string (e.g., '/users/{id}')",
      "required_scopes": ["string"],
      "sufficient_scope": "string (single scope that grants access if multiple alternatives exist)",
      "least_privilege_example": "string (example of minimal scope assignment for this endpoint)",
      "notes": "string (any caveats, conditional requirements, or resource-specific rules)"
    }
  ],
  "undocumented_endpoints": [
    {
      "method": "string",
      "path": "string",
      "warning": "string (why this endpoint appears undocumented or unscoped)"
    }
  ],
  "over_scoped_warnings": [
    {
      "endpoint": "string",
      "current_scopes": ["string"],
      "recommended_scopes": ["string"],
      "risk": "string (what an attacker could do with the excess scope)"
    }
  ]
}

## CONSTRAINTS
- Every endpoint in [API_SPEC] must appear in the endpoint_mappings array exactly once.
- If an endpoint requires different scopes based on the resource or caller role, document all variants in the notes field.
- For each scope, explain why it is not split further or why it is not combined with another scope.
- Flag any endpoint that appears to have no documented scope requirement as an undocumented_endpoint.
- If an endpoint's current scope assignment appears broader than necessary, add an over_scoped_warning with a specific least-privilege recommendation.
- Use the exact scope strings from [SCOPE_DEFINITIONS] if provided. If none are provided, propose a consistent scope naming convention.
- Do not invent endpoints. Only map what is present in [API_SPEC].

## EXAMPLES
[EXAMPLES]

## RISK_LEVEL
[RISK_LEVEL]

To adapt this template, replace [API_SPEC] with your OpenAPI document, a structured endpoint list, or a markdown table of routes. If you have existing scope definitions, paste them into [SCOPE_DEFINITIONS] to constrain the model to your current naming convention. The [EXAMPLES] placeholder should contain one or two correct mapping rows showing your preferred format and scope granularity. Set [RISK_LEVEL] to 'high' if the API handles financial, healthcare, or PII data—this signals the model to apply stricter scrutiny to over-scoped warnings and to flag any endpoint that lacks a documented scope requirement.

Before shipping this prompt into production, validate the output against your actual API route table to catch hallucinated endpoints. Run a diff between the generated mapping and your existing permissions configuration to surface discrepancies. For high-risk APIs, require a human reviewer to approve every over_scoped_warning and undocumented_endpoint entry before the table is published. Wire the output into a CI check that fails if the number of mapped endpoints does not match the number of routes in your OpenAPI spec.

This prompt is not a one-off generator; it is a structured extraction and reasoning step inside a documentation pipeline. The implementation harness must accept an API specification (OpenAPI, a route manifest, or a code-annotated endpoint list) and an auth configuration (scope definitions, role-to-scope mappings) as inputs. The harness should pre-process these inputs into a normalized format before calling the model, ensuring the prompt receives a clean, deduplicated list of endpoints and scopes. Post-processing must parse the generated table into a structured format (JSON or CSV) for downstream consumption by static site generators, API reference renderers, or review tools.

Validation and retry logic is critical because scope-per-endpoint tables are security-sensitive. After the model returns a table, run a deterministic validator that checks: (1) every endpoint in the input spec appears in the output table, (2) every scope referenced in the output table is defined in the input auth configuration, (3) no endpoint is assigned a scope that grants more access than the endpoint's HTTP method and path imply (e.g., a GET endpoint should not require a write scope), and (4) the table contains no hallucinated endpoints or scopes. If validation fails, construct a retry prompt that includes the specific validation errors and asks the model to correct only the failing rows. Limit retries to two attempts; if validation still fails, flag the output for human review and log the failure with the input spec, auth config, model response, and validator output for debugging.

Model choice and tool use should favor models with strong structured output support (GPT-4o, Claude 3.5 Sonnet, or equivalent) and use structured output modes or tool-calling with a strict JSON schema for the mapping table. Do not rely on free-text parsing. The schema should define each row as an object with fields: endpoint_path, http_method, required_scopes (array of strings), scope_rationale (string), and least_privilege_example (string). For large APIs with more than 50 endpoints, split the input into batches by resource or tag and run the prompt per batch, then merge and deduplicate the results. Implement a human review gate for any output where the model assigns admin-level scopes to public endpoints, where scope assignments contradict existing documentation, or where the validator flags unresolved errors after retries. Log every generation with the prompt version, model, input hashes, validation results, and review status for auditability.

Integration into a docs pipeline typically means the validated table is committed to a version-controlled data file (e.g., scope-matrix.json) that feeds a documentation site generator. Set up a CI check that runs the prompt against the current API spec and auth config on every PR that modifies either input, comparing the generated table against the committed version. If differences exceed a threshold (e.g., more than 5% of rows changed), block the merge and require a human to approve the diff. This prevents silent scope documentation drift. For runtime use in API gateways or authorization middleware, export the validated table as a machine-readable policy file, but always keep the human-reviewed documentation version as the source of truth.