How to fix "apiKey security scheme name is required" in OpenAPI

An OpenAPI security scheme with type: apiKey must state the exact header, query parameter, or cookie name that carries the key.

Broken YAML

This scheme gives the location but omits the transmitted name:

openapi: 3.1.0
info:
  title: Reports API
  version: 1.0.0
security:
  - ApiKeyAuth: []
paths: {}
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header

Why it fails

type: apiKey requires both name and in. The name is the wire-level field, such as X-API-Key. The component key ApiKeyAuth is only the local identifier used by Security Requirement Objects.

Redocly reports The field name must be present on this level at the Security Scheme Object. Without name, generated docs and clients cannot know where to put the credential.

Corrected YAML

Declare the exact request header:

openapi: 3.1.0
info:
  title: Reports API
  version: 1.0.0
security:
  - ApiKeyAuth: []
paths: {}
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

Header names are case-insensitive on the wire, but use the spelling shown in your API documentation. For a cookie or query key, set in: cookie or in: query and use its actual field name.

OpenAPI 3.0 vs 3.1

OpenAPI 3.0 and OpenAPI 3.1 use the same required fields for an API key scheme: type, name, and in. Both versions allow query, header, or cookie as the location.

This syntax differs from HTTP bearer authentication. A bearer scheme uses type: http and scheme: bearer; it does not use name or in.

Specification sections: OpenAPI 3.0.4 and OpenAPI 3.1.1.

Validate the fix

Save the complete document as openapi.yaml, then run:

pnpm --package=@redocly/cli@2.53.3 dlx redocly lint openapi.yaml --extends=minimal

The corrected scheme removes the structural missing-name error. Validation does not test a credential against the live API.