####################
Token Authentication
####################

The Token Authentication, also known as Token Bearer, method uses an
additional header when passing the request for authentication. This
token is generated from the "Token Retrieval Endpoint".

To use the Token Authentication method, you must select
*"Token Authentication"* as the value for the "Authentication Type" field.

The fields used to configure Token Authentication include:

 * **Username:** This field provides the username when requesting the token
   from "Token Retrieval Endpoint". This field is optional.

 * **Password:** This field provides the password when requesting the token
   from "Token Retrieval Endpoint". This field is optional.

 * **Token Retrieval Endpoint:** This field provides the URL for
   generating the token that is used in the data request. This field is
   required.

 * **Authorization Header:**  This field describes the name of the header to
   be sent. Default: Authorization. This field is optional.

 * **Bearer Token Format:** This field describes how the content should be
   sent. The format allows for a single substitution for the token. This
   substitution occurs when specifying ``{}`` in the format. For example,
   if you wanted to use ``Bearer <token>`` you would input ``Bearer {}``.
   Default: {}. This field is optional.

 * **Token Key:** This field states the key where the token exists in the
   returned JSON dictionary. This field is required.


*******
Example
*******

You must make a request to a web-server (data server) that
requires a token from another web-server (token server). The
data server expects the header ``Auth: CoolBeans <token>``.
The token server generates tokens at ``https://token.info``
with the credentials *my_user/password4321* and returns the
following format:

.. code:: javascript

    {
        "token": "<the_token_to_use>",
        "expires": "900s"
    }

To configure Token Authentication, the following fields are required:

 * Username: my_user
 * Password: password4321
 * Token Retrieval Endpoint: https://token.info
 * Token Key: token
 * Authorization Header: Auth
 * Bearer Token Format: CoolBeans {}