Security scheme ApiKey parameter clarification

[Fresa]

Security scheme object can define apiKey as security type where in (parameter location) and name (parameter name) is required. It doesn't say anything about whether this parameter needs to be defined by the operation that uses the scheme.

Should it?
Can it?

If it can, then can two operations reference the same api key security object, but declare two different schemas for the parameter?

If there is no parameter defined, how should the parameter's schema be interpret? Empty schema?

[handrews]

@Fresa in the Parameter Object, the name field states:

If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored.

Since the API Key goes in the Authorization header, this means you cannot put it in both places. You can only set the Authorization header via a Security Scheme Object and a Security Requirement Object.

[Fresa]

An apiKey security object define where the key goes (in) and what the parameter name is (name), or is the specification incorrect?
This is the example in the specification:

type: apiKey
name: api-key
in: header

[handrews]

@Fresa my apologies, you are correct, I was confusing api-key with HTTP basic auth, which automatically goes in Authorization in a specific format.

But I would say that based on that restriction, you would not re-define the API key header as a Parameter Object. It's clear that Security Schemes are intended to take precedence.

If you put them in both places, the behavior is undefined (meaning that since we don't define behavior, tools can do whatever they want, which probably won't be the same from one tool to another, so... don't do that).

[Fresa]

@handrews no worries, and thanks for your reply!

Do you by any chance have any insight on why a parameter object was not chosen instead of in and name, similar to the response header object?

That in combination with instructions on the security object stating that a parameter defined on the security scheme object shall/should be inherited would make intent clearer, and it would give an opportunity to define a schema for the parameter.

[handrews]

@Fresa no, I'm afraid that pre-dates my involvement and I've not heard a reason from anyone else.

But the inconsistencies between the Parameter Object, Header Object, and Security Scheme Object are things we are looking at for when we eventually do a syntax clean-up for 4.0. There will likely be at least a 3.3 first, as we need to try out some other improvements in the security/authn/authz areas, and we'd like to get feedback on those before rewriting the syntax. One of those things would be adding flexibility on controlling this sort of thing, although I'm not sure what approach we'll take. We're waiting to see how quickly 3.2 is adopted before deciding the whens/whats of the next minor or major release anyway. Although so far we're getting positive feedback on how easy it is to update from 3.1.