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
You can find your API key in your Nexmo account [developer
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!
Originally published at LornaJane.