Scopes specified for an incompatible security scheme

Description

In OpenAPI 3.0, scopes apply only to oauth2 and openIdConnect security schemes. Specifying scopes for an apiKey or http scheme makes the documented security requirements inconsistent with that scheme.

Potential impact

Validation tools may reject the document, or API users may request unsupported scopes.

Remediation

Use an empty array [] for apiKey and http security requirements. For oauth2 or openIdConnect, specify the scopes actually required and keep them consistent with the identity provider's configuration.

Examples

The example removes scopes from api_key and retains the OAuth2 scopes. Separate array entries are alternatives, so they do not require both authentication methods. Use the OAuth2 authorization code flow with PKCE.

Before

json

{
  "openapi": "3.0.0",
  "info": {
    "title": "Simple API Overview",
    "version": "1.0.0"
  },
  "security": [
    {
      "api_key": [
        "write:api",
        "read:api"
      ]
    },
    {
      "petstore_auth": [
        "write:pets",
        "read:pets"
      ]
    }
  ],
  "paths": {},
  "components": {
    "securitySchemes": {
      "api_key": {
        "type": "apiKey",
        "name": "api_key",
        "in": "header"
      },
      "petstore_auth": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://example.org/api/oauth/dialog",
            "tokenUrl": "https://example.org/api/oauth/token",
            "scopes": {
              "write:pets": "modify pets in your account",
              "read:pets": "read your pets"
            }
          }
        }
      }
    }
  }
}

After