{
  "id": 12788701,
  "title": "Multiple security schemes in OpenAPI: AND vs OR, optional auth, and per-operation overrides",
  "url": "https://urgent.news/2026/10/08/multiple-security-schemes-in-openapi-and-vs-or-optional-auth-and-per",
  "topic": "tech",
  "section": "Tech",
  "published": "2026-10-08T04:45:19.000Z",
  "source": {
    "name": "Dev.to",
    "slug": "dev-to",
    "url": "https://dev.to/jeff_pdc/multiple-security-schemes-in-openapi-and-vs-or-optional-auth-and-per-operation-overrides-1m3b"
  },
  "original_language": "en",
  "account": "The security keyword in OpenAPI is an array of alternatives, where each alternative is a set of schemes that must all be satisfied. A common mistake is to confuse the outer array with the inner object, leading to either too little or too much protection for endpoints. Understanding security as an OR of ANDs can help clarify multi-authentication designs.\n\nIn YAML, the security keyword can be written as separate objects for each scheme, or as a single object containing multiple schemes. For example, security: - apiKeyAuth: [] oauth2: [ read: orders ] requires the caller to provide both an API key and an OAuth token.\n\nTo express either an API key or OAuth, use two separate array elements: security: - apiKeyAuth: [] - oauth2: [ read: orders ]. This allows for greater flexibility in authentication schemes.\n\nA single array element containing two schemes requires the caller to send both required credentials, while defining schemes once under components.securitySchemes and referencing them with the security keyword keeps the declarations organized.\n\nGlobal defaults for authentication can be set at the root level and overridden for specific operations. For example, security: - bearerAuth: [] sets a default global bearer token requirement, which can be overridden for individual endpoints.\n\nOperation-level security replaces the global security entirely, meaning it does not merge. This behavior is often misinterpreted, leading to incorrect implementation. For instance, security: - bearerAuth: [] paths: /public/status: get security: [] explicitly sets an unauthenticated operation, overriding the global bearer token requirement.\n\nIn cases where an endpoint requires the global scheme in addition to an extra one, the global scheme must be restated within the operation's requirement. Optional authentication that returns different data based on credentials should be explicitly defined using an empty alternative alongside the authenticated one: security: - {} - bearerAuth: [] - apiKeyAuth: [].\n\nFor OAuth2 and OpenID Connect, the scope list inside a requirement is an AND over scopes, meaning the token must carry every listed scope. Assign each operation the minimum set of scopes it needs to ensure least privilege. For example, /orders: post security: - oauth2: [ write:orders ] handles write operations, while /orders/{id}: get security: - oauth2: [ read:orders ] handles read operations.\n\nWhen an endpoint accepts either scoped OAuth or a simpler API key, list them as separate requirement objects to avoid confusion. Document that the API key may carry different rate limits or permissions, ensuring clear communication between clients and servers.\n\nMutual TLS (mTLS) and cookie/session authentication are modeled differently than header-based authentication. mTLS uses type: mutualTLS, while cookie/session auth is represented as type: apiKey. These methods are not sent as headers but occur at the transport level.",
  "summary": "The security keyword is small and surprisingly easy to invert. It is an array of alternatives, where each alternative is itself a set of schemes that must all be satisfied. Miss the distinction between the outer array and the inner object and you either leave a sensitive endpoint protected by a single factor when you required two, or force credentials on an endpoint that was meant to be public.…",
  "key_points": [],
  "editors_take": "The OpenAPI security keyword's array structure, where each element represents an AND of schemes, allows for flexible authentication designs, including optional auth, overrides, and combinations of schemes that meet specific endpoint needs.",
  "illustration": null,
  "coverage": {
    "outlets": 1,
    "also_reported_by": []
  },
  "ai_generated": true,
  "disclaimer": "Summaries, key points and the editor’s take are written by software from other outlets’ reporting and may contain errors — always check the linked original."
}