Sometimes developers fail to provide the access token in the right way. I observed various errors which were not easy to spot, when supporting developers who were stuck with a 401 Unauthorized response.

Let's take this example line in bash script:
curl -v $KC_HOST/admin/realms/example/users/count --header "Authorization: Bearer $ACCESS_TOKEN"

The following bugs could be in the script:

• Token is empty: Authorization: Bearer is sent
• Variable not replaced: Authorization: Bearer $ACCESSS_TOKEN is sent
• Complete token response send: Authorization: Bearer { "access_token"="ey...} is sent
• Expired token sent
• Wrong token sent (e.g. ID token or refresh token)

All those cases could be detected more easily with a helpful error description in the API response.

Actual Keycloak Response

In all of the cases above Keycloak response is

< HTTP/1.1 401 Unauthorized
< Date: Tue, 05 Aug 2025 13:50:32 GMT
< Content-Type: application/json
<  ...
{"error":"HTTP 401 Unauthorized"}

RFC 6750 Recommendation

RFC 6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage recommends to provide a WWW-Authenticate header which should be used to help debugging such faulty requests:

Example from RFC:

     WWW-Authenticate: Bearer realm="example",
                       error="invalid_token",
                       error_description="The access token expired"

Proposal in case of 401 response

Admin API should sent the WWW-Authenticate header with error="invalid_token" and helpful error_description like the following:

• Token is empty
• Token is not a JWT
• Token expired
• Token is not an access token

Example Request: Authorization: Bearer $ACCESSS_TOKEN is sent
Example response

     WWW-Authenticate: Bearer error="invalid_token",
                       error_description="Token is not a JWT"