Ask a Question

Two potential naming issues with api key authentication within SwaggerHub UI

New Contributor

Two potential naming issues with api key authentication within SwaggerHub UI

I’m admittedly new to Swagger, and I’m having a hard time getting api_key working the way I believe it should be within the SwaggerHub UI. 


The documentation at says:


“Add an entry with type: apiKey in the global securityDefinitions section. The entry name can be arbitrary (such as APIKeyHeader in the example below) and is used to refer to this security definition from other parts of the spec.” (my b/i/u emphasis added)


And provides this example:



But if I use the following YAML in SwaggerHub, which has two identical securitySchemes with only an "x" added to the end of the "entry name" of one of them:

openapi: 3.0.0
  version: "0.0.1"
  title: Test
  - description: Test
      summary: 'api blah test 2'
      description: 'Something goes here'
      operationId: apiBlahTest
        - api_keyx: []
          description: Success
      type: apiKey
      name: api_keyxx
      in: header
      type: apiKey
      name: api_keyxx
      in: header


with the security for /blah set to 'api_keyx', if in SwaggerHub I click the `/blah` and then the lock icon, it shows nothing for available authorizations:



But if I remove the 'x' at the end and change the `/blah`'s security to:

        - api_key: []


And then click the /blah lock icon, I get content in the authorizations dialog:



The `name` displayed within the pop-up does not reflect the name defined in the YAML, which I assume it would show in the dialog as `Name: api_keyxx` to match the YAML.


So two notes:

  1. The “entry name” does not appear to be arbitrary, if it is not specifically named “api_key” it doesn’t seem to appear in the SwaggerHub UI
  2. The entry’s “name” attribute (not to be confused with the “entry name”) does not appear to be reflected in the UI. The "name" seems to always be "api_key" (perhaps because it is using the "entry name" instead of the attribute "name"?

Am I doing something wrong, am I misunderstanding something(s), is the SwaggerHub UI presenting some bugs, or is it some combination thereof?


Thank you for any guidance.






SmartBear Alumni (Retired)

Hi James,


I did some tests with security schemes, and the issue with empty authorizations list occurs if I import an external API definition containing security schemes, or add a new security scheme into an existing API. Saving the API and refreshing the page resolves the issue. Can you see if the issue persists after you refresh the editor page?


As for your questions about UI rendering of security scheme names vs their HTTP header names, hope this image helps clarify that:



Helen Kosova
SmartBear Documentation Team Lead
Did my reply answer your question? Give Kudos or Accept it as a Solution to help others. ⬇️⬇️⬇️

Thank you for your reply. That is the functionality I was expecting, but not getting.


It seems like refreshing the page triggered a "save" warning, so I let it save and after the refresh it was behaving as expected. However, after playing with it more, I was able to get it to break again. I updated the "name" attribute in YAML, let the UI "catch up" to the edit, then clicked the lock icon and the authorization dialog shows still shows the old value. You can see the updated YAML in the background and the old name value in the dialog.



It seems like there is a bug where the UI stops fully reflecting the YAML contents. Some parts of the UI keep working, but other parts do not.


I see a variety of cross-site warnings in the browser console, a TypeError, and some 404 errors. I'm not sure of any of these messages are related to the problem I'm experiencing.


I am using Chrome Version 84.0.4147.105 (Official Build) (64-bit)



SmartBear Alumni (Retired)

Thanks for the additional details, I've passed them to the developers. To track the issue status you can open a support ticket and reference this thread and issue # STEAM-3967.


The workaround seems to be to Save & refresh the editor after any changes in security schemes.

Helen Kosova
SmartBear Documentation Team Lead
Did my reply answer your question? Give Kudos or Accept it as a Solution to help others. ⬇️⬇️⬇️

One more wrinkle: sometimes when I'm editing, I do not have a "Save" button at the top and it will be "Create New Version" instead. When this happens and I hit refresh, the page refreshes and I get a warning about unsaved changes, and usually my most recent edits are lost. At this point the button at the top says "Save" again and I can click it. It appears to remain "Save" for some period of time but at some point it is or becomes "Create New Version" and at that point I can no longer manually save my edits to the current version before hitting refresh.


Thank you for your assistance. I will create a ticket.

Showing results for 
Search instead for 
Did you mean: