Using an API Key & Secret for Swagger Security Scheme

Question

Swagger supports security of api key, but that seems to be limited to a single parameter.

Is there a way to define a set of parameters (key and secret) that are expected as parameters in a request?

Or is the only way just to skip the security scheme, and just add those parameters to every request?

Answer 1

Yes, OpenAPI (Swagger) 2.0 and 3.0 let you define multiple security definitions and mark an operation as requiring multiple securities, such as a pair of API keys.

In the following example, I'm defining two API keys, Key and SecretKey, both of which should be present in the headers of each request in order to get authenticated.

swagger: '2.0'
info:
  version: 0.0.0
  title: Simple API
securityDefinitions:
  key:
    type: apiKey
    in: header
    name: Key
  secret_key:
    type: apiKey
    in: header
    name: SecretKey

# Or if you use OpenAPI 3.0:
# components:
#   securitySchemes:
#     key:
#       type: apiKey
#       in: header
#       name: Key
#     secret_key:
#       type: apiKey
#       in: header
#       name: SecretKey

paths:
  /:
    get:
      # Both 'Key' and 'SecretKey' must be used together
      security:
        - key: []
          secret_key: []
      responses:
        200:
          description: OK

Note that this is different from

      security:
        - key: []
        - secret_key: []  # <-- Note the leading dash here

which means the endpoint expects either Key or SecretKey, but not both.