security scheme apiKey in body form data parameter

[johakoch]

It is possible to define a security scheme as

QueryKey:
  type: apiKey
  in: query
  name: myparam

corresponding to

parameters:
  - name: myparam
    in: query
    required: true

while the first approach adds the notion that the required parameter is related to security.

However there seems to be no way to define a security scheme about a required parameter in an application/x-www-form-urlencoded body adding the same security notion.

[MikeRalphson]

Can you clarify if this is a question or a feature request? If the former, no it's not currently possible. If the latter, do you have an actual API which uses an API key in a request body?

[johakoch]

The question: Are there reasons against such a feature?

Regarding an actual API:

The OAuth2 token endpoint requires the client to authenticate via

• Basic Auth using client_id:client_secret, OR
• sending client_id AND client_secret parameters in the POST request

This could be specified as

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    ClientIdPost:
      type: apiKey
      in: ???
      name: client_id
    ClientSecretPost:
      type: apiKey
      in: ???
      name: client_id
paths:
  "/token":
    post:
      security:
        - BasicAuth: []
        - ClientIdPost: []
          ClientSecretPost: []

[MikeRalphson]

There is already an oauth2 securityScheme type which encapsulates this logic, it's not necessary to use apiKey types for this.

[johakoch]

I understand the type oauth2 securityScheme to indicate that an API user has to get an access token from the OAuth2 server as specified by the type oauth2 securityScheme.

But this does not help if you want to describe the API of the OAuth2 server itself using OpenAPI.

[MikeRalphson]

But this does not help if you want to describe the API of the OAuth2 server itself using OpenAPI.

Though oAuth2 operates over HTTP and can be said to have an API, I wonder whether it is itself an "HTTP API" within the meaning of the phrase used by the OpenAPI Specification, and there whether it is in scope here.

[waldbaerkoch]

The OAuth2 token endpoint was just an example. There could, of course, be more (and maybe more appropriate ones).
Now, why can I specify a security scheme for a query parameter, but not a parameter in an application/x-www-form-urlencoded body?
My question, again: Are there reasons against such a feature? Is the answer to the question, that this security scheme would only apply to methods with defined message bodies, which would violate some (to me currently unknown) design principle for OpenAPI?

[dylantack]

I would find this feature helpful. Mandrill is one example that expects the API key in a body parameter:

https://mandrillapp.com/api/docs/messages.curl.html#sts=/messages/search.json

[johakoch]

@dylantack wrote:
I would find this feature helpful. Mandrill is one example that expects the API key in a body parameter:

https://mandrillapp.com/api/docs/messages.curl.html#sts=/messages/search.json

My question was about an API key in an application/x-www-form-urlencoded body. But, of course, it can be extended to other content-types, like application/json as in the Mandrill example.

[henrikhorluck]

This seems related/ necessary for OAI/sig-security#19? Specifically the client authentication method using client_assertion and client_assertion_type are sent as a parameters in the body using application/x-www-form-urlencoded

[handrews]

To clarify, does this boil down to adding a new value for in in the Security Scheme Object to indicate that the API Key is in the body? Which is assumed to be ...form-urlencoded?

[StuartMoncrieff]

Another REST API that includes the ApiKey in the POST body is the NeoLoad Data Exchange API: https://documentation.tricentis.com/neoload/2024.1/en/content/apis/data_exchange_api_data_model.htm (see the "Create a session with an API Key" example).