Security Schemes and Requirements

Documenting how clients authenticate

Authentication methods are declared once in components/securitySchemes and then applied with security requirements. Scheme types: apiKey (a key in a header, query parameter or cookie, with name and in); http with scheme: basic or scheme: bearer (optionally bearerFormat: JWT); oauth2 with one or more flows; openIdConnect with a discovery URL; and mutualTLS (3.1) for client certificates. The top-level security field sets a default for all operations, and each operation can override it: security: [] makes an operation public (such as a health check or login), and a list of alternatives means any one suffices, while several schemes in the same requirement object must all be satisfied. Documentation tools use these declarations to render "Authorize" buttons, and generators wire authentication into SDKs. OpenAPI only describes security; it does not enforce it. Your gateway or application must still validate credentials, and should never place secrets such as API keys in query strings, where they end up in logs.

Security declared once, applied everywhere

Schemes are defined in components; operations reference them as requirements.

Bearer tokens by default, API keys for partners, a public health check

Alternatives are listed separately; an empty array means no authentication.

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    partnerKey:
      type: apiKey
      in: header
      name: X-Partner-Key

security:
  - bearerAuth: []                     # default for every operation

paths:
  /health:
    get:
      operationId: health
      security: []                     # public
      responses: { '200': { description: OK } }
  /partner/orders:
    get:
      operationId: listPartnerOrders
      security:
        - partnerKey: []               # either a partner key ...
        - bearerAuth: []               # ... or a user token
      responses: { '200': { description: Orders } }

Document 401 and 403 too

Declaring a security scheme is not enough for clients. Document the 401 (missing or invalid credentials) and 403 (authenticated but not allowed) responses with their error bodies, so integrators can handle them.

त्वरित जाँच: What does `security: []` on an operation mean?

• The operation is forbidden
• All security schemes are required
• The operation requires no authentication, overriding the global default
• The document is invalid