{"templateId":"markdown","versions":[{"version":"v1","label":"1.x (archive)","link":"/docs/cli/v1/rules/common/security-scopes-defined","default":false,"active":false,"folderId":"6f4800fc"},{"version":"v2","label":"2.x (current)","link":"/docs/cli/rules/common/security-scopes-defined","default":true,"active":true,"folderId":"6f4800fc"}],"sharedDataIds":{"sidebar":"sidebar-docs-cli.sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"redocly_category":"Redocly CLI","type":"markdown"},"seo":{"title":"security-scopes-defined","description":"OpenAPI-generated documentation tool with 24k+ stars on Github - make APIs your company's superpower.","siteUrl":"https://redocly.com","image":"/assets/redocly-card.f670aae34a39545a5ea633a540cb3a4a333a1f23bb2ed3c4a1b17a5fbcf0ac85.db81178d.png","lang":"en-US"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"security-scopes-defined","__idx":0},"children":["security-scopes-defined"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Requires that every scope used in a security requirement is defined in the corresponding OAuth2 security scheme."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"OAS"},"children":["OAS"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Compatibility"},"children":["Compatibility"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2.0"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3.0"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3.1"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3.2"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]}]}]}]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"AsyncAPI"},"children":["AsyncAPI"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Compatibility"},"children":["Compatibility"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2.6"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3.0"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["✅"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The rule checks security schemes of type ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["oauth2"]},", where the set of valid scopes is declared in the API description:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OpenAPI 3.x and AsyncAPI 2.6"]},": scopes used in security requirements must be declared in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scopes"]}," of at least one of the scheme's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flows"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OpenAPI 2.0"]},": scopes used in security requirements must be declared in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scopes"]}," of the scheme."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["AsyncAPI 3.0"]},": scopes listed in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scopes"]}," of a security scheme must be declared in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["availableScopes"]}," of at least one of the scheme's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["flows"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Other scheme types are skipped: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openIdConnect"]}," scopes are defined behind the discovery URL and can't be checked statically."," ","For the remaining types OpenAPI 3.1 and later allow arbitrary role names."," ","Requirements that reference undefined security schemes are skipped as well — those are reported by the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/cli/rules/oas/security-defined"},"children":["security-defined"]}," rule."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api-design-principles","__idx":1},"children":["API design principles"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A scope that is used in a security requirement but not declared in the security scheme is almost always a typo or a leftover from a renamed scope."," ","Clients generated or configured from such a description request permissions that don't exist, and fail at authorization time."," ","This rule catches the mismatch early and suggests the closest declared scope."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configuration","__idx":2},"children":["Configuration"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Option"},"children":["Option"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["severity"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Possible values: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["off"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warn"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]},". Default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warn"]}," (in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recommended"]}," configuration)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["requireScopes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Requires every ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["oauth2"]}," security requirement to list at least one scope. Default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An example configuration:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"rules:\n  security-scopes-defined:\n    severity: error\n    requireScopes: true\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"examples","__idx":3},"children":["Examples"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Given this configuration:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"rules:\n  security-scopes-defined: error\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example of an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["incorrect"]}," security requirement — the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["read:pet"]}," scope is not defined in the scheme:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"paths:\n  /pets:\n    get:\n      security:\n        - petstore_auth:\n            - read:pet\ncomponents:\n  securitySchemes:\n    petstore_auth:\n      type: oauth2\n      flows:\n        authorizationCode:\n          authorizationUrl: https://example.com/authorize\n          tokenUrl: https://example.com/token\n          scopes:\n            read:pets: Read pets\n            write:pets: Write pets\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example of a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["correct"]}," security requirement:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"paths:\n  /pets:\n    get:\n      security:\n        - petstore_auth:\n            - read:pets\ncomponents:\n  securitySchemes:\n    petstore_auth:\n      type: oauth2\n      flows:\n        authorizationCode:\n          authorizationUrl: https://example.com/authorize\n          tokenUrl: https://example.com/token\n          scopes:\n            read:pets: Read pets\n            write:pets: Write pets\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-rules","__idx":4},"children":["Related rules"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/cli/rules/oas/security-defined"},"children":["security-defined"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/cli/rules/oas/no-unused-components"},"children":["no-unused-components"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/cli/rules/configurable-rules"},"children":["configurable rules"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":5},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/common/security-scopes-defined.ts"},"children":["Rule source for OpenAPI and AsyncAPI 2.6"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/async3/security-scopes-defined.ts"},"children":["Rule source for AsyncAPI 3.0"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/openapi-visual-reference/security-schemes/"},"children":["Security scheme docs"]}]}]}]},"headings":[{"value":"security-scopes-defined","id":"security-scopes-defined","depth":1},{"value":"API design principles","id":"api-design-principles","depth":2},{"value":"Configuration","id":"configuration","depth":2},{"value":"Examples","id":"examples","depth":2},{"value":"Related rules","id":"related-rules","depth":2},{"value":"Resources","id":"resources","depth":2}],"frontmatter":{"slug":"/docs/cli/rules/common/security-scopes-defined","seo":{"title":"security-scopes-defined"}},"lastModified":"2026-07-21T13:21:49.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/cli/rules/common/security-scopes-defined","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}