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

Every request requires two tokens: an app token and a user token.  App tokens are meant to live long-term, and only
expired when desired.  A user token is intended to last for about 24 hours (configurable in full installations), and
provides the context for those requests.

Basic token (login) requests are one of the few traditional POSTs in the system, in case you need to make this
request through a traditional browser form, and accepts a username and password.  It looks like the following::

    curl -X POST -H "App-Token: [APP_TOKEN]" -d "username=[username]&password=[password]" \
        https://<yournamehere>.enfixlp.com/api/v1/token/

Your token return will look like::

    {"token": "8031ac4ce22c"}

Creating Application Tokens
---------------------------

Application tokens are managed in the same fashion as the other REST endpoints, with a few differences:

    #. PUT is not allowed.
    #. You cannot specify your own token string, you can only specify the expiration.

There is no maximum expiration date.  By default, application tokens expire about 200 years from now
(configurable in full installations).
That should be plenty of time for you to refresh your tokens!

To create a new application token::

    curl -X POST -H "App-Token: [APP_TOKEN]" -H "Token: [TOKEN]" -H "Content-Type: application/json" \
        -d '{"seconds_until_expire": 86400}' \
        "https://<yournamehere>.enfixlp.com/api/v1/app_tokens/"

If you successfully create an app token, you'll receive the following response::

    {"app_token": "5aa59576866e4167b26c8430fd4e4d29"}

Authenticating On Behalf Of Another User (aka OBO Tokens)
---------------------------------------------------------

If you want to be able to generate tokens on behalf of (OBO) another user, there's a "tokens" endpoint that works
very similarly to the Application Tokens endpoint above.  It has the same limitations.  Default expiration is a day
(configurable in full installations).

To create an OBO token::

    curl -X POST -H "App-Token: [APP_TOKEN]" -H "Token: [TOKEN]" -H "Content-Type: application/json" \
        -d '{"seconds_until_expire": 86400, "user": "52c5fc24a64c9efc0f253535"}' \
        "https://<yournamehere>.enfixlp.com/api/v1/tokens/"

The user field is the ID of the user you're updating.

If you successfully create an OBO token, you'll receive the following response::

    {"token": "e3bb632cd0d441a2adc9fc47507cf3fe"}

If you specify an invalid user ID, you should receive the following error::

    {
        "errors": {
            "user": "One or more IDs are not formatted correctly."
        }
    }

Changing a Token's Expiration
-----------------------------

Both tokens and app tokens can have their expiration date changed or set in the past as a way to immediatley invalidate
without necessarily deleting all record of the token.  It's done as a PATCH operation just like the other PATCH
operations elsewhere in the API, and is set via ``seconds_until_expire``.  This value is always from the current moment
in time, so setting it to -1 or less will immediately expire the token.

Deleting a Token
----------------

If you must remove a token or app token, the standard DELETE verb works on it.  The ID is the same as the token itself,
so specifying that as part of the token/app token URL path will be sufficient.