What HTTP code should I use for a third party authentication failure?

Question

I'm creating an application that has integrations with third party applications.

To do this, the logged in user submits an API key for the third party integration.

In the case that the API key they submitted is invalid - (and returns a 401 from the third party), which HTTP response should I return?

Returning a 401 from my application sounds confusing because from the frontend's point of view, it's unclear whether they're unauthenticated by my application, or the third party application.

I'm tempted to just give it a 400 - as if they'd submitted a form with an invalid email address etc.

Answer 1

The question seems to imply the authentication failure is the fault of the client making the request. In that case, if I had to pick a code, I would probably choose to return 403 Forbidden.

RFC 7231 §6.5.3 describes the 403 code as follows:

The 403 (Forbidden) status code indicates that the server understood the request but refuses to authorize it. A server that wishes to make public why the request has been forbidden can describe that reason in the response payload (if any).

If authentication credentials were provided in the request, the server considers them insufficient to grant access. The client SHOULD NOT automatically repeat the request with the same credentials. The client MAY repeat the request with new or different credentials. However, a request might be forbidden for reasons unrelated to the credentials.

An origin server that wishes to "hide" the current existence of a forbidden target resource MAY instead respond with a status code of 404 (Not Found).

This status code is commonly used as a generic 'authentication failed' response and isn't likely to trigger any specific authentication mechanism, like 401 can compel a browser to show a username/password prompt. The specific reason why authentication failed can be described in the response body, either in a machine-readable form (e.g. JSON or XML), or as a human-readable document (e.g. HTML).

Code 400 isn't the worst possible choice here, but it's rather generic.

Answer 2

You can use status code HTTP status code - 407 (Proxy Authentication Required). From Mozilla Developers Reference:

The HTTP 407 Proxy Authentication Required client error status response code indicates that the request has not been applied because it lacks valid authentication credentials for a proxy server that is between the browser and the server that can access the requested resource.

Your backend-application is acting like a proxy to 3rd party API, so it is OK to use 407 in this case.

Answer 3

407 is not correct. In this case, your code is the proxy and it is authenticated. It is a foreign system that is not authenticated.

401 is reasonable but it is misleading about what is not authenticated since the client is authenticated to your system. This also does not work if your foreign auth is deferred until after a 100Continue.

400 is not correct since the request was valid in format but the auth failed at the foreign agent.

All the other 4xx responses are easily dismissed as not applicable here.

So, that leaves 403 Forbidden which in my opinion is your only real option in this case:

403 Forbidden The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401, the client's identity is known to the server. Responding also with a status message that indicates "root cause" of failure may be suitable in this case too. It really depends on the security disposition of your application.

My $.02