.. _authentication_chapter:

Authenticating to the Recras API
================================

Most of the Recras API endpoints are limited to authenticated requests.
A very limited number is publicly accessible, usually with limited funcationality and information.

API Keys
--------

Authenticating to the Recras APIs is preferably done with `API Keys`_, which can be created in the Recras interface.
Present your API key in an ``Authorization: Bearer`` header, as specified in `RFC 6750`_.

   **Example request**:
   
   .. sourcecode:: http
   
      GET /api2/personeel/me HTTP/1.1
      Host: demo.recras.nl
      Authorization: Bearer asdfhjklaoed

   **Example response**:

   .. sourcecode:: http
   
      HTTP/1.1 200 OK
      Content-Type: application/json

      {
         "fields": "values"
      }

Username:password
-----------------

Alternatively, API requests can be authenticated with `HTTP Basic Authentication(https://en.wikipedia.org/wiki/Basic_access_authentication)`, but this method should be considered deprecated since July 2020.

   **Example request**:

   .. sourcecode:: http

      GET /api2/personeel/me HTTP/1.1
      Host: demo.recras.nl
      Authorization: Basic YmVoZWVyOmRlbW8=

   **Example response**:

   .. sourcecode:: http

      HTTP/1.1 200 OK
      Content-Type: application/json

      {
         "fields": "values"
      }

.. _`RFC 6750`: https://tools.ietf.org/html/rfc6750#section-6.1.1