I've been working on a few OpenAPI descriptions of APIs lately, and really enjoying the benefits they bring. In particular the ability to import into Postman as a collection I think is a "killer feature" for APIs looking to get developers up and running quickly. The catch? I found that an API that needs an API key and secret, or a username and password/token, is supposed to be described with multiple security schemes - but this does not play nicely with tools like Postman.

To work around this problem, I changed the security schemes to describe a single API key field (it's a query parameter). This is well understood by all tools, and also most of them will just pick the first one when multiple are specified. Then I added the API secret field as a required parameter to all the endpoints.

This isn't an ideal situation, because the secret really is part of the auth, not a parameter. However I did find that it helped not only my Postman import, but also use of Prism as a mock server, and that some documentation tools rendered the required fields for each endpoint more clearly.

As things stand, I have a single security scheme listed in the components: section:

  securitySchemes:
    apiKey:
      type: apiKey
      name: api_key
      in: query
      description: >-
        You can find your API key in your Nexmo account [developer
        dashboard](https://dashboard.nexmo.com/)

Then for each endpoint, I added the additional parameter (described in the parameters: section of components: and using a $ref). This is perhaps less formally correct, but more working, than what I had before - so I'm living with it for now.

If you want to see the spec in action, it's here: https://github.com/Nexmo/api-specification/blob/master/definitions/verify.yml and if you have any better ideas, I'd love to hear them!