Skip to main content

How to complete the authentication failed challenge

By Published

How to complete the authentication failed with username and password challenge by adding a Basic Auth header with the wrong details. In response the API returns a status code of 401.

Authentication Challenge

Most of the challenges simply require the correct payload, and an X-Challenger header to track the session. The authentication challenges require an extra header, the value for which can only be obtained with a username and password.

GET /api/secret/token (401) - Authentication Failed

Issue a GET request on the /api/secret/token end point and receive 401 when Basic auth username/password is not admin/password

  • GET request means use the HTTP Verb GET
    • e.g. GET /api/secret/token sends to the secret token endpoint
  • Basic auth means include the Basic Authorization header
  • username/password is not admin/password the authorisation header value is base 64 encoded, and the details should not match admin as the username, and password for the password
  • add the X-CHALLENGER header to track progress and because the authentication code we need is associated with the X-CHALLENGER session
  • Receive a 401 response

Basic Instructions

  • Create a new request for the /api/secret/token end point
    • if running locally that endpoint would be
      • https://apichallenges.com/api/secret/token
  • The verb should be a GET
  • Add a Basic Auth header by selecting "Basic" from the "Auth" tab and entering a username and password but make sure it is not admin/password e.g. use username "Admin1", password "Pa55word" (or anything else you want)
  • No request body is needed
  • You should receive a 401 response - meaning "Unauthorized" because you entered the wrong username or password
  • The request should have an X-CHALLENGER header to track challenge completion

Try it now

GET /api/secret/token with invalid credentials to trigger 401

Example Request

> GET /api/secret/token HTTP/1.1
> Host: apichallenges.com
> User-Agent: rest-client
> X-CHALLENGER: x-challenger-guid
> Authorization: Basic YWRtaW46cGFzc3dvcmRk
> Accept: */*

Example Response

< HTTP/1.1 401 Unauthorized
< Connection: close
< Date: Sat, 24 Jul 2021 11:13:04 GMT
< Www-Authenticate: Basic realm="User Visible Realm"
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Headers: *
< X-Challenger: x-challenger-guid
< Server: Jetty(9.4.z-SNAPSHOT)
< Via: 1.1 vegur

The Authorization header does not send the username and password in plain text, it uses Base64 to obscure the details.

You could see what username and password I used by typing the Base64 string YWRtaW46cGFzc3dvcmRk into a Base64 decoder like https://www.base64decode.org/

Or you could decode it in the browser dev console by typing:

atob('YWRtaW46cGFzc3dvcmRk')

The command to encode a string as base64 is btoa

Although we add an "Authorization" header, really we are trying to "authenticate" with a set of user details.

  • Authorization is "do you have the right permissions"
  • Authentication is "are you who you say you are"

Additional Exercises

  • try creating a base64 Authorization header by hand, without using the "Auth" tab in Insomnia

Lessons Learned

  • 401 Unauthorized on /api/secret/token means authentication failed before any authorization token exists.
  • Bad or missing Basic Auth should not return an X-AUTH-TOKEN.
  • Authentication failures are useful for checking WWW-Authenticate or challenge headers if provided.

Suggested Experiments

  • Send no Authorization header, then send an incorrectly encoded Basic value, and compare the error responses.
  • Correct only the password while keeping the same request shape to confirm the failure was credential-specific.
Experiment with this endpoint

 

Copyright Compendium Developments Ltd 2020 - 2026