How To Define Auth Keys inside of Swagger?

(Justincrabbe) #1

I’m trying to work out an issue and the response from support is below:

“We don’t support the ability to directly control request header parameters like you would with the other parameter types. However, if your API endpoints use certain standard auth schemes (like basic, API key, or OAuth), then you can define those in the Swagger.”

How can I define two elements (keys) within the swagger file?

(Taylor Barnett) #2

@justincrabbe This makes sense why you were getting a 403 even though you had your authentication set in the headers correctly.

It is possible to model API keys inside of your OpenAPI Specification (formerly known as Swagger) document. But I don’t think this is going to work with the Algolia API like you want it to.

I checked out their docs, and it looks like this is the way you are suppose to do authentication:

I don’t see any mention of authentication in other ways than headers. So sadly, you might have to find another way of using this API in your project that allows you to set request header parameters .

(Justincrabbe) #3

Ok I took your note over to the forum for Dropsource and they suggested as follows. Is this possible inside of Spotlight?

From the instructions -

Dropsource does not currently provide the ability to set custom request headers inside the editor - however, depending on what data you need to pass in the header of a request, you may be able to achieve this via your Swagger/OpenAPI specification. One of our users recently asked if it would be possible to include two pieces of data in the header of a request - this is the guidance we gave them:

Include your two variables in the “securityDefinitions” in your Swagger and in each route that you need these variables to be sent for, you can set values for them inside Dropsource in the auth modal you’ll see in the API tab next to the API name (rather than in the parameters section of the request).

(Taylor Barnett) #4

I believe you should be able to do that. I was able to test it out with the information you sent me.

First, you will create these in the security section:

Then, you will add it to the endpoint in the security property:

You will need to then follow Dropsource’s instructions for how to set these properties. I can’t help on this part.

(Justincrabbe) #5

Hi Taylor,

So you helped me greatly with this but i’m still having issues inside of dropsource.

For some reason it looks like the application ID isn’t being passed as a header value or something… the api key is and that’s great but the application id isn’t.

I’m attaching the Postman working call and also the Console screenshot showing the call being made resulting in the 403.

(Taylor Barnett) #6

Hey again!

Did you try it the way Dropsource suggested? Because it sounds like you’ll never be able to pass it in as a header value. Only through the security section in OpenAPI like I shared in the last post.

Sadly, neither of these are running through Stoplight, so we won’t be of much use. I can only help you set it in your OpenAPI document.

(Justincrabbe) #7

I think there is a missing setting or something on the spotlight end.

One other has got it to work via Spotlight it appears and I’m trying to understand how.

Is the issue with me on my end point 2?:

Not sure why you’re still not getting this to work. I just tried it and it works perfectly.
You simply just need to add the headers as api keys as i pointed out above.

Here is a quick rundown with stoplight.

  1. Use the security to create the two headers as shown below:

image.png817x536 23.3 KB

  1. Create your algolia endpoint. E.g. search index like below. Remember the search index endpoint has a path parameter, e.g. here i’m calling it indexName . So create a path parameter and use it in the endpoint url (put it inside curly brackets as shown).

image.png978x884 43.6 KB

  1. Finally define your body and response. This will depend on the algolia endpoint. For search index you just need to define a query object which will be the search string. The response will depend on the structure of your data (records). You can model that by using postman to make the call and copy the response and use it in stoplight to define the response.

image.png984x733 35.7 KB

(Taylor Barnett) #8

Did you set it up exactly like they have? What’s the error code you are getting now? Something other than the 403?

(Justincrabbe) #9

I have added the security settings it seems only, but not step 2 or 3 because they don’t seem to be visible here:

How do I add the “path paramater” value and the “body and response” (step 3) in the way that seems to be working and tested according to the user in the Dropsource forum?

(Taylor Barnett) #10

For 2, you need to go into the get operation itself to set that.

I believe you already did 3.

(Justincrabbe) #11


In my case, I have only one index, and i added the index into the URL as a fixed value (Airport) - why would i still need a path paramater is my thought?


Furthermore, in the example by the user inside of Dropsource (above) who got it working some how, they are using a POST call vs. a GET call and I just want to be sure that is noted with respect to the above settings.

(Taylor Barnett) #12

The way the endpoint is structure and GET vs POST all depends on what endpoint you are using from the Algolia API. That’s beyond where I can help with this.

(Justincrabbe) #13

Thanks, but what about the fixed value for the index paramater? Why have a path param is my thought it’s in the url?

(Taylor Barnett) #14

I’m not sure if I can accurately answer that without knowing more about the endpoint you are using, like does the index change ever? This all really depends on how the API is designed and how you will be using it.