Defining Multiple Security Schemes and When a Client Sends the Wrong One

When a single API supports multiple security schemes, the client must select the appropriate one, or it can encounter confusing issues. For example, a service might require a JWT for user-facing operations, an API key for partner webhooks, and a client certificate for admin tasks. If the contract does not clearly define which scheme is needed for each operation, generic clients often send the wrong credential, resulting in a 401 error that can be misleading.

The problem arises because the server typically returns a generic 401 or 403, making it unclear whether the issue is a missing or malformed credential or a simple wrong type. The client, seeing only an authentication failure, may rotate credentials without realizing the root cause is that the wrong scheme was sent.

To avoid these issues, it's best to declare the security schemes explicitly at the operation level rather than using a global default. This allows clients to read the contract and know exactly which credential to present for each operation. If an endpoint supports multiple schemes, list them as separate alternatives in the security array, clearly indicating that only one is required.

Hard-coding the Authorization header per request is not recommended, as it bypasses the contract and increases the likelihood of sending the wrong scheme. Instead, configure the generated client with a credential provider for each scheme. This ensures the correct credential is attached automatically based on the operation's security requirement, keeps secrets out of individual call sites, and makes adding new schemes as simple as a configuration change.

To verify that the correct scheme is being used, you can add tests that call each operation with a mock and check that the outgoing request contains the expected credential type and placement. Include negative tests that send the wrong scheme to confirm the 401 error is surfaced with enough context to identify the scheme mismatch. For mTLS routes, verify that the certificate is actually presented during the handshake.

In summary, when a client sends the wrong security scheme, it's almost always because the contract does not explicitly declare the required scheme for each operation. By declaring the schemes once in the components, attaching the exact requirement to each operation, and using the generated client to select credentials, you can avoid this common pitfall and ensure your API is secure and easy to use.