feat: Add scopes support to apiKey securityScheme

[joekir]

Summary

Currently, the apiKey security scheme does not support scopes/permissions, unlike OAuth2. This means that when an API uses API key authentication with granular permissions, there is no native way to document these in the spec and developers must resort to documenting permissions in the description field of each operation.

Current Behaviour

API key security schemes only support an empty array in the security requirement object:

Copy code
security:
  - ApiKeyAuth: []  # scopes cannot be defined here

Desired Behaviour

Allow scopes to be defined on apiKey security schemes, similar to oauth2:

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      scopes:
        banana.read: Grants read access to bananas
        banana.write: Grants write access to bananas

paths:
  /v1/banana:
    get:
      security:
        - ApiKeyAuth:
            - banana.read  # 👈 currently not possible

Use Case

Many APIs use API keys with granular permission models. Without native scope support, tooling such as documentation generators, SDK generators and API gateways cannot automatically understand or enforce permissions, leading to:

• Permissions being buried in description fields
• Loss of machine-readable permission metadata
• Inconsistent documentation across teams

Alternatives Considered

Documenting permissions in the description field - works but is not machine-readable
Switching to OAuth2 - not always feasible for simpler APIs that use API keys, or misleading if the API is not OAuth2 and just leveraging this feature