.. _authenticating:

==============
Authenticating
==============

Review Board has two methods that can be used for authentication: The
login URL and HTTP Basic Authentication.

Basic HTTP Authentication is new in Review Board 1.5, and is the preferred
method for authentication. The login URL was introduced in Review Board 1.0
and will remain as an alternative for the next couple of releases.

Either method requires a login and password and, upon completion, will
send a ``rbsessionid`` cookie that the client must use for all further
requests. The cookie will be valid for a year.


Login URL
=========

To log in using the dedicated login URL, send an HTTP POST to
``/api/json/accounts/login/`` with the following fields:

* ``username``
* ``password``

See the :ref:`api-login` docs for more information.


Basic HTTP Authentication
=========================

Starting with Review Board 1.5, every request that requires authentication
will fail with an HTTP 403: Unauthorized status if the client hasn't
already authenticated.

This response will contain a ``WWW-Authenticate`` header to set
``Basic realm="Web API"``.

The client must respond with an ``Authorization`` header in the next
request to the URL. The contents of this will be :samp:`Basic {base64-auth}`.
The ``base64-auth`` part is a base64-encoded representation of the string
:samp:`{username}:{password}`.

For example, for a username and password of ``joe`` and ``mypass``, you
will base64-encode the string ``joe:mypass`` to get the resulting string
``am9lOm15cGFzcw==``, which you would then send as ``Basic am9lOm15cGFzcw==``.


Logging Out
===========

To log the client out, send an HTTP POST to ``/api/json/accounts/logout/``.
No data needs to be sent in this request. The server-side session information
will be removed and the ``rbsessionid`` cookie will be invalidated.

See the :ref:`api-logout` docs for more information.


.. comment: vim: ft=rst et ts=3
