OpenAPI Security: API Keys, Schemas, and Auth

An OpenAPI document can say a route requires OAuth while the handler accepts a missing token. It can also omit a tenant permission that the server correctly enforces. Treat the document as a contract to compare with behavior, not a security control by itself. The OpenAPI 3.1.1 specification defines security schemes and operation requirements; OWASP API Security explains why object and function authorization still matter.

Start with one route

Choose one protected operation and record its method, effective OpenAPI security requirement, credential location, server authentication check, tenant permission rule, request fields, and response fields. Run a valid caller, missing credential, wrong tenant, injected protected field, and response-secret assertion against an owned fixture. Use the apiKey repair below only when its declaration is wrong; use the readOnly/writeOnly repair only when the generated request or response shape is wrong. Keep the runtime authorization result separate from both document repairs.

How do you fix an apiKey scheme with a missing name?

For type: apiKey, set both name and in. The component identifier, such as WorkspaceKey, is only a reference within the document. It is not the header name. This complete OpenAPI 3.1 example requires the X-Workspace-Key header on one operation:

openapi: 3.1.0
info:
  title: Workspace API
  version: 1.0.0
paths:
  /workspace:
    get:
      operationId: getWorkspace
      security:
        - WorkspaceKey: []
      responses:
        '200':
          description: Authorized workspace response
        '401':
          description: Missing or invalid credential
components:
  securitySchemes:
    WorkspaceKey:
      type: apiKey
      in: header
      name: X-Workspace-Key

The same fields apply in OpenAPI 3.0. The location can be header, query, or cookie; use the location the server actually reads. For bearer authentication, use type: http and scheme: bearer, not this API-key shape. Swagger's API-key guide explains the declaration.

Rerun your validator after the repair. Inspect a generated request and confirm that its header matches the server contract. Test a missing key and a deliberately wrong key in your owned test environment. A valid document can still describe a route that accepts unauthenticated requests.

Route-method-security matrix

For each sensitive operation, record the declared scheme and scopes, the actual server check, the object owner rule, and the expected response without valid credentials.

A global security requirement can be overridden at an operation. Review the effective requirement, not only the top of the document. Check alternate methods and old API versions. A schema that lists a bearer token does not show whether the server validates issuer, audience, membership, or role.

Check security requirement logic

In OpenAPI, two schemes in one Security Requirement Object are AND: both must be satisfied. Separate objects in the security array are OR: either can satisfy the operation. An empty object makes authentication optional. An operation-level security field overrides the top-level field; an empty list can remove the inherited requirement. Mark these cases in the matrix before testing the route. A generated client and a server may interpret a mistaken declaration differently.

What if a generator ignores readOnly or writeOnly?

A model reused for input and output can expose the wrong fields in a generated client. For example, an id marked readOnly: true might still appear in a create-request type. A deliverySecret marked writeOnly: true might appear in a response type. Inspect the generated types and serializers for your exact generator version. A field in a TypeScript interface is not proof that the server returns it.

When directional annotations do not produce the required client shape, separate the schemas. This fragment makes the intended fields explicit:

components:
  schemas:
    MessageCreate:
      type: object
      additionalProperties: false
      required: [text, deliverySecret]
      properties:
        text:
          type: string
        deliverySecret:
          type: string
          writeOnly: true
    Message:
      type: object
      additionalProperties: false
      required: [id, text]
      properties:
        id:
          type: string
          readOnly: true
        text:
          type: string

Reference #/components/schemas/MessageCreate in the operation's requestBody.content.application/json.schema. Reference #/components/schemas/Message in its successful response schema. Regenerate and compile a small caller. Its create request must not require a server-assigned ID. Its response type must not promise the secret.

OpenAPI 3.0 defines directional behavior for these fields, including how required applies. In 3.1, readOnly and writeOnly are JSON Schema annotations; a generic validator does not become a request/response policy engine. See the 3.0 Schema Object and 3.1 Schema Object.

The repair also needs server checks. Submit a synthetic create request with an injected id and confirm that it cannot change the assigned identity. Confirm that responses, exports, and logs do not contain the synthetic secret. Configure the server's validation and output serialization explicitly. Merely adding additionalProperties: false to a document does not install validation in an application.

Test the contract

Use a synthetic tenant fixture. For each row, test a valid token, a missing token, a token for the wrong audience, and a valid user without the required tenant grant. Record actual status, body, and side effects. If a route intentionally supports anonymous access, confirm that its returned fields are public. Add a CI diff check when a route or security requirement changes.

The artifact is a route-method-security matrix that names both declaration and implementation. A generic checklist is not proof that an API passed review. A mismatch is a repair task; it is not an authorized finding against a third party. Keep tests within owned systems or a written review scope.