.. _mes-api-token-tutorial:

API Token Tutorial 
====================

As with most service providers, we want to expose our system to allow customers to export and import data from our system using automation and interfacing other API's.  To use our system via API, we have a simple integration setup. 

Steps to getting an API Key 
---------------------------

1) (Optional) Create a 'Service-User' user
2) (Optional) Test Service-User login
3) Get a persistent API Key via the /api_tokens/ endpoint of our system
4) Enter the persistent API in the system connecting to our API's


(Optional) Create a 'Service-User' user
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You get an API key for an individual user, but we strongly suggest creating a 'Service-User' in  the system for each integration, to track access and changes by automated systems.  This can be done via your own Authentise Admin, or one of our customer support agents. 

We require a unique email for this, often we have customers use 'service-X@customer.com' email,  or sometimes use the + syntax to notify the right person on events. Such as 'serviceX+employee@customer.com'.  

This is a user to represent your automation's input into the session. 
Often these are named by the 'Service' with email of 'service_name@your_company.com' 

(Optional) Test Service-User login
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you do create a Service-User, we strongly recommend doing a quick  general log-on to the system, to make sure no typos or errors were made in the setup. 


Get a persistent API Key via the /api_tokens/ endpoint
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Using the verified account, you can now access and save an API key, to use for long-term access to our API.  If you want a pre-built example of getting an `API Token`_ for use in your API. 

.. _API Token: https://github.com/Authentise/Example-Authentise-Session


Enter the persistent API in the system connecting to our API's
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This depends on your system, but the quickest way to connect to the system would be use use HTTP standard `Basic Auth`_  to the API Key as your access token to the Authentise Service.

.. sourcecode:: python

    def make_request(self, url, data):
        "Example of calling the API using the API Key to request data from an endpoint"
        auth = HTTPBasicAuth(self.api_auth["uuid"], self.api_auth["secret"])
        return requests.post(url.format(self.host), auth=auth, data=data, verify=self.verify_ssl)


.. _Basic Auth: https://en.wikipedia.org/wiki/Basic_access_authentication

Python Example Code
^^^^^^^^^^^^^^^^^^^^

Authentise has provided some python example code of using this system at `Github Repo <https://github.com/Authentise/Example-Authentise-Session>`_. This is probably the best way to begin using our system, and to understand common development patterns.