Best way to describe global client identification parameters?

[LukeHagar]

I am working on documenting the Plex Media Server API, and they have a number of header parameters that are used to identify clients.

There is only one apiKey ("X-Plex-Token"), but it seems like populating all of the rest of the headers as apiKeys in a set is really the only viable option, especially when trying to generate SDK tools.

anyone have any insight or advice on better ways to accomplish this?

[ponelat]

Hi @LukeHagar ,

You can add headers in two ways:

- As a parameter (in: header)

- As a security requirement

If you're looking to have these headers across the entire API, all operations you _might_ want to use security, where you can use the root-level `security: ...` field. See https://swagger.io/docs/specification/authentication/.

For bulk-adding parameters. This is a challenge to other folks too, a proposal was started to help with it called "Overlays" which is a separate document to do bulk modifications to an OpenAPI file, see: https://github.com/OAI/Overlay-Specification. The spec would allow you to say things like: "Add this parameter to every operation".

Related is the idea of "traits" which is a grouping of $refs. This isn't supported by OpenAPI (today) it might be in a later version of the spec.