In Rails API token authentication, what is the realm="Application" section of the www-Authenticate header?

Question

I have a rails app with this controller:

class EpisodesController < ApplicationController
  before_action :authenticate

  def index
    episodes = Episode.all
    render json: episodes, status: 200
  end

  protected
    def authenticate
      authenticate_or_request_with_http_token do |token, options|
        User.find_by(auth_token: token)
      end
    end
end

If I send this curl request, I get back this response with these headers:

$ curl -IH "Authorization: Token token=fake" http://localhost:3000/episodes.json
HTTP/1.1 401 Unauthorized 
Content-Type: text/html; charset=utf-8
WWW-Authenticate: Token realm="Application"

What is the www-authenticate header used for? Is it just convention? What is the realm="application" used for? I read this:

The Token part means that the given resource uses token authentication. The resource under that URI is currently part of the “Application” realm. The realm value allows protected resources to be partitioned into different sets of protection spaces, each with its own access policies.

But I don't get it...

Answer 1

The WWW-Authenticate Header must be included with 401 Unauthorized responses (see HTTP 1.1 RFC) so it's not only a convention.

With the value you can indicate which authentication mechanism is supported (in this case Token, another auth scheme could be Basic for Basic Authentication). The realm can be set to any value you want and should identify the secure area. In case of Basic Auth this value will be displayed on the login dialog.