OpenAPI Description using API key and secret

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!

Leave a Reply

Please use [code] and [/code] around any source code you wish to share.

This site uses Akismet to reduce spam. Learn how your comment data is processed.

To respond on your own website, enter the URL of your response which should contain a link to this post's permalink URL. Your response will then appear (possibly after moderation) on this page. Want to update or remove your response? Update or delete your post and re-enter your post's URL again. (Find out more about Webmentions.)