Authentication
==============

All API methods require you to authenticate yourself. We use `OAuth 2`_ for this, in particular we use the following
grant types:

- ``client_credentials`` to authenticate clients for non-user specific tasks
- ``password`` to authenticate users
- ``refresh_token`` to refresh a user token once it expires

.. _`OAuth 2`: https://oauth.net/2/

POST /oauth/v2/token
--------------------

Returns an access token valid for up to an hour.

Authenticating a client
~~~~~~~~~~~~~~~~~~~~~~~

Example request for client authentication:

.. code-block:: text

  POST /oauth/v2/token

.. code-block:: json

  {
    "grant_type": "client_credentials",
    "client_id": "abc123",
    "client_secret": "456789"
  }

Example response for client authentication:

.. code-block:: json

  {
    "access_token": "MTI1ZWFkNDBmYjOGVmMGI0YzRjMGMzZGE4MQ",
    "expires_in": 3600,
    "token_type": "bearer",
    "scope": null
  }

Authenticating a user
~~~~~~~~~~~~~~~~~~~~~

To authenticate a user, their username and password have to be posted to the token endpoint. This endpoint requires:
- the client ID
- the client secret
- the grant type must be `password`
- the username
- the password

The password can be either a regular password set by the user, or a OTP (One Time Password). One time passwords can be
requested either using a web form, or the `Request a One Time Password (OTP)`_ endpoint. The OTP are usually short
lived, and are sent to the user via email or SMS.

Example request for user authentication:

.. code-block:: text

  POST /oauth/v2/token

.. code-block:: json

  {
    "grant_type": "password",
    "client_id": "abc123",
    "client_secret": "456789",
    "username": "someone@example.com",
    "password": "def56789"
  }

Example response for client authentication:

.. code-block:: json

  {
    "access_token": "MTI1ZWFkNDBmYjOGVmMGI0YzRjMGMzZGE4MQ",
    "expires_in": 3600,
    "token_type": "bearer",
    "scope": null,
    "refresh_token": "NmI5ZGI3MzBmZjYwY2E1ZTlkYTM4MTJlMmI1Z"
  }

Request a One Time Password (OTP)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To request a one time password, you can send a user's email address to the endpoint below. If the user does not exist,
a new user might be created for them to login. This depends on the security settings of that particular TAG instance.

An email will be triggered to the specified email address, with the user's short lived OTP in it. One time passwords
can be used only once.

.. code-block:: text

  POST /otp/send

.. code-block:: json

  {
    "email": "someone@example.com"
  }

Refreshing a user access token
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Example request for user authentication:

.. code-block:: text

  POST /oauth/v2/token

.. code-block:: json

  {
    "grant_type": "refresh_token",
    "client_id": "abc123",
    "client_secret": "456789",
    "refresh_token": "NmI5ZGI3MzBmZjYwY2E1ZTlkYTM4MTJlMmI1Z"
  }

Example response for client authentication:

.. code-block:: json

  {
    "access_token": "ZDdkODE4Y2FkMzM4ZDcxZDIxM2M0ZjE2MTE4NG",
    "expires_in": 3600,
    "token_type": "bearer",
    "scope": null,
    "refresh_token": "YWYyMzI2ZjM1ZWVjODZhM2FkMWQwMTEzMjQ5NGF"
  }