Undefined OAuth2 scope in an OpenAPI 3 operation

Description

An OpenAPI 3.0 operation's security requirements are inconsistent with the documented permissions when they reference a scope missing from the corresponding OAuth2 scheme's flows.

Potential impact

API users may request tokens with the wrong scope or implement the operation's permission requirements incorrectly.

Remediation

Align the operation's required scopes with the OAuth2 scopes under components.securitySchemes and the authorization server's configuration. Add missing definitions for required permissions. Operation-level requirements replace global security, so retain the permissions that are still needed.

Examples

The example removes an unnecessary error:api reference from the operation. Compare OpenID Connect scopes with the provider's configuration instead of local OAuth2 flow definitions.

Before

json

{
  "openapi": "3.0.0",
  "paths": {
    "/": {
      "get": {
        "security": [
          {
            "oAuth2AuthCode": [
              "read:api",
              "error:api"
            ]
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oAuth2AuthCode": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://api.example.com/oauth/authorize",
            "tokenUrl": "https://api.example.com/oauth/token",
            "scopes": {
              "read:api": "read your apis"
            }
          }
        }
      }
    }
  }
}

After