Documentation about REST API should mention, that the Header to pass the API Key is "X-Api-Key"

[in-fke]

Current Behavior

Documentation about REST API (and possibly Swagger Auth Info) does not mention or specify, that the Header to pass the API Key is "X-Api-Key".

Existing docs (along with Swagger)
https://docs.dependencytrack.org/integrations/rest-api/

Proposed Behavior

Documentation about REST API (and possibly Swagger Auth Info) should mention, that the Header to pass the API Key is "X-Api-Key".

Info about OpenAPI Spec to document specific header:
https://swagger.io/docs/specification/v3_0/authentication/api-keys/

Checklist

• I have read and understand the contributing guidelines
• I have checked the existing issues for whether this enhancement was already requested

[jakub-bochenski]

I think it should be possible to pass the API key using standard Authenticaton header

It has two benefits:

• documentation: it's the standard
• security: most software will filter out Authentication header when logging, but won't know about a custom header

[in-fke]

I think it should be possible to pass the API key using standard Authenticaton header

You probably mean the header by the name Authorization, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Authorization
Agree, but this ticket is firstly about the documentation of the existing implementation.

security: most software will filter out Authentication header when logging, but won't know about a custom header

There's also the aspect that application gateways filter out any non-standard header unless you explicitly allow them.
This is the reason I stumbled upon looking for the header name in the first place...
Another reason to use the Authorization header.

[nscuro]

@in-fke Where would you expect this information to be? We already declare the header in the OpenAPI Authorization section and you should be able to see that in Swagger UI:

[in-fke]

Thanks for quick follow-up, I actually oversaw it, it's there

    "securitySchemes" : {
      "ApiKeyAuth" : {
        "type" : "apiKey",
        "name" : "X-Api-Key",
        "in" : "header"
      },
      "BearerAuth" : {
        "type" : "http",
        "scheme" : "Bearer"
      },
      "ApiKeyQueryAuth" : {
        "type" : "apiKey",
        "name" : "apiKey",
        "in" : "query"
      }
    }

Assuming that I would not be able to find it anywhere, my suggestion was to also write it here:
https://docs.dependencytrack.org/integrations/rest-api/
but then again, that would be redundant. Maybe some wording like "For authorization headers, please refer to the OpenAPI spec."
(yet, that may not be worth a PR).
So going by the spec, Authorization: Bearer <apiKey> would already work? I did not bother trying it, I just noticed that the Maven Plugin for uploading SBOM uses that special "X-Api-Key" header, see https://github.com/search?q=repo%3Apmckeown%2Fdependency-track-maven-plugin%20X-Api-Key&type=code and it's giving us trouble because the header is not being forwarded by a Reverse Proxy.

[nscuro]

So going by the spec, Authorization: Bearer <apiKey> would already work?

The bearer authorization only works for users.

When a user logs in to DT, they receive a bearer token which they then use to authenticate to the API (the frontend is an SPA so it's just an API client).

API keys are not bearer tokens and thus are communicated through a different header.

While we could allow something like:

Authorization: ApiKey ...

I don't believe this scheme can be defined in OpenAPI.