{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-learn/ai-for-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"redocly_category":"Learn","type":"markdown"},"seo":{"title":"Use AI to check authentication and authorization patterns","description":"Spot missing scopes, inconsistent security schemes, and thin auth error docs in OpenAPI with a model, then enforce fixes with Redocly CLI lint before merge.","siteUrl":"https://redocly.com","image":"/assets/redocly-card.f670aae34a39545a5ea633a540cb3a4a333a1f23bb2ed3c4a1b17a5fbcf0ac85.db81178d.png","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"use-ai-to-check-authentication-and-authorization-patterns","__idx":0},"children":["Use AI to check authentication and authorization patterns"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can ask a model to read your OpenAPI security model before handlers ship, then run the same file through Redocly CLI lint in the pull request. The learn article ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/learn/ai-for-docs/ai-reviews"},"children":["Use AI to accelerate and improve reviews"]}," covers the wider review pattern; here the focus stays on schemes, scopes, route coverage, and the error contracts integrators need when credentials fail."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"why-auth-and-authorization-drift-in-api-descriptions","__idx":1},"children":["Why auth and authorization drift in API descriptions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Teams add endpoints faster than they update ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["components.securitySchemes"]},". One route still documents API keys while the rest moved to OAuth2. Admin paths inherit a global bearer scheme but never list the scopes a caller needs. Documentation mentions 401 and 403 in prose while the spec only declares a generic 400."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A model can compare many paths at once and ask whether each operation matches the story you tell about roles and trust boundaries. It does not replace threat modeling, but it gives you a patient reader for long YAML."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"inputs-that-keep-the-review-grounded","__idx":2},"children":["Inputs that keep the review grounded"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Paste a short auth model in plain language before the spec excerpt. Name actors (for example integrators, support staff, machine clients), which routes are public, and which actions require elevated roles."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List invariants you already enforce in code, such as tenant isolation on every read, or that destructive verbs always require an admin scope. If the file is large, scope the excerpt to the surface you are changing and describe the rest in a sentence."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"auth-context-block-you-can-paste","__idx":3},"children":["Auth context block you can paste"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"Auth model: OAuth2 client credentials for integrators; session cookies for the dashboard.\nPublic: GET /status, GET /openapi.json\nRoles: reader (read-only), admin (write + delete)\n\nReview securitySchemes, security requirements, and auth-related responses:\n[paste OpenAPI excerpt]\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prompt-skeleton-for-auth-and-authorization","__idx":4},"children":["Prompt skeleton for auth and authorization"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep the ask structured so findings are easy to triage."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"markdown","header":{"controls":{"copy":{}}},"source":"You are reviewing authentication and authorization for [one sentence domain].\n\nPlease list:\n1. Operations that should require credentials but have no security requirement.\n2. Mismatches between security scheme names in operations and components.securitySchemes.\n3. Missing or inconsistent OAuth scopes (or permissions) across related endpoints.\n4. Operations that share a scheme but should differ by role or scope.\n5. Missing or vague 401 and 403 responses, including whether examples match the scheme.\n6. Public routes that should explicitly document security: [] if they are intentionally open.\n\n[paste OpenAPI or notes]\n","lang":"markdown"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"signals-models-often-surface","__idx":5},"children":["Signals models often surface"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Across teams, reviews tend to cluster on a short set of themes. Orphan schemes appear when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["components.securitySchemes"]}," defines a name operations never reference. Scope gaps show up when write endpoints document fewer scopes than read endpoints on the same resource. Error gaps cluster when only 200 responses are declared, or when 401 and 403 reuse the same schema without explaining retry versus forbidden. Inheritance confusion happens when a global ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["security"]}," block hides which routes are actually public."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Treat the list as a prioritized backlog, not a verdict. Some routes are intentionally open, and some schemes are legacy until a migration finishes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"thin-before-and-after-on-security","__idx":6},"children":["Thin before and after on security"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"paths:\n /reports:\n get:\n summary: Download usage report\n security:\n - bearerAuth: []\ncomponents:\n securitySchemes:\n BearerAuth:\n type: http\n scheme: bearer\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"paths:\n /reports:\n get:\n summary: Download usage report\n security:\n - BearerAuth: [reports:read]\n responses:\n '401':\n description: Missing or invalid bearer token\n '403':\n description: Caller lacks reports:read scope\ncomponents:\n securitySchemes:\n BearerAuth:\n type: http\n scheme: bearer\n bearerFormat: JWT\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The second sketch does not prove your threat model is complete, but it shows how a review nudges you toward aligned names, explicit scopes, and distinct failure responses before implementation hardens the wrong shape."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"graph LR\n A[Auth model plus OpenAPI] --> B[Model review]\n B --> C[Human edits]\n C --> D[redocly lint]\n D --> E[Pull request]\n","diagramHtml":"

Auth model plus OpenAPI

Model review

Human edits

redocly lint

Pull request

","diagramHtmlDark":"

Auth model plus OpenAPI

Model review

Human edits

redocly lint

Pull request

"},"children":["graph LR\n A[Auth model plus OpenAPI] --> B[Model review]\n B --> C[Human edits]\n C --> D[redocly lint]\n D --> E[Pull request]\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Run the loop while the document is still cheap to edit."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"where-cli-lint-takes-over","__idx":7},"children":["Where CLI lint takes over"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you accept changes, run the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/commands/lint"},"children":["lint command"]}," against the same file the model saw. Lint applies preprocessors and rules, reports problems in OpenAPI and related formats, and does not run decorators, which keeps this step focused on spec compliance rather than publishing transforms."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/rules/built-in-rules"},"children":["built-in rules"]}," catalog includes security-related checks. The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/rules/oas/security-defined"},"children":["security-defined rule"]}," verifies that every operation or global security requirement is defined. If an API is intentionally public, the rule documentation shows declaring an empty requirement so readers know the omission is deliberate:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"security: []\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In continuous integration, point the same command at pull requests so every spec edit repeats local checks. Models sometimes suggest scheme names or extensions your ruleset has not whitelisted yet, and lint surfaces those mismatches early."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you have no local config yet, the command defaults to the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/rules/recommended"},"children":["recommended ruleset"]},". As standards mature, add ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/rules/configurable-rules"},"children":["configurable rules"]}," for org-specific auth policies, such as requiring scope text in operation descriptions or forbidding duplicate scheme types on one path. The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/guides/configure-rules"},"children":["guide to configuring a ruleset"]}," walks through a practical baseline."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Organizations that treat OpenAPI as law usually centralize how rules are authored and shared. The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/api-standards"},"children":["API standards and governance"]}," page describes using the same configuration locally and in automation so developers see the same violations everywhere."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":8},"children":["Best practices"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ship the auth model as a short checklist, not a long policy essay, in the same message as the spec excerpt."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Review one theme at a time on large files: scheme names first, then scopes, then error responses."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Log model findings as tickets with path and operation anchors so humans can accept or reject with traceability."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Combine model passes with deterministic tools so subjective completeness meets objective gates, which mirrors the guidance in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/learn/ai-for-docs/ai-reviews"},"children":["Use AI to accelerate and improve reviews"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-this-pairing-cannot-replace","__idx":9},"children":["What this pairing cannot replace"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Models do not know your live identity provider configuration, token lifetimes, or penetration test results unless you state them. They can suggest scopes that sound reasonable but do not match what your authorization service enforces. Lint cannot judge whether a scope is too broad for a role; it checks that the document obeys the rules you configured."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"summary","__idx":10},"children":["Summary"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use a structured prompt plus a plain-language auth model to surface scheme, scope, and error gaps early, then let Redocly CLI enforce the rules your team already agreed to. Keep humans in the loop for trade-offs, and treat automation as a safety net rather than a substitute for security review."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"learn-more","__idx":11},"children":["Learn more"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you are ready to wire the deterministic side of the loop, start with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/"},"children":["Explore Redocly CLI"]}," for installation, first commands, and how lint fits alongside bundling and preview workflows described in the broader ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/rules"},"children":["rulesets"]}," documentation."]}]},"headings":[{"value":"Use AI to check authentication and authorization patterns","id":"use-ai-to-check-authentication-and-authorization-patterns","depth":1},{"value":"Why auth and authorization drift in API descriptions","id":"why-auth-and-authorization-drift-in-api-descriptions","depth":2},{"value":"Inputs that keep the review grounded","id":"inputs-that-keep-the-review-grounded","depth":2},{"value":"Auth context block you can paste","id":"auth-context-block-you-can-paste","depth":3},{"value":"Prompt skeleton for auth and authorization","id":"prompt-skeleton-for-auth-and-authorization","depth":2},{"value":"Signals models often surface","id":"signals-models-often-surface","depth":2},{"value":"Thin before and after on security","id":"thin-before-and-after-on-security","depth":2},{"value":"Where CLI lint takes over","id":"where-cli-lint-takes-over","depth":2},{"value":"Best practices","id":"best-practices","depth":2},{"value":"What this pairing cannot replace","id":"what-this-pairing-cannot-replace","depth":2},{"value":"Summary","id":"summary","depth":2},{"value":"Learn more","id":"learn-more","depth":2}],"frontmatter":{"seo":{"title":"Use AI to check authentication and authorization patterns","description":"Spot missing scopes, inconsistent security schemes, and thin auth error docs in OpenAPI with a model, then enforce fixes with Redocly CLI lint before merge."}},"lastModified":"2026-05-22T12:10:40.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/learn/ai-for-docs/ai-auth-authorization-patterns","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}