.. authentication

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

To authenticate with the one-mnhs API, you'll first need to create an account and
generate your API credentials token `here <https://vital-records.mnhs.io/rma/api>`_.

Once you've got a credentials token, you can sign in to the API and get a session 
"access token" at the ``/auth/sign-in-with-api-creds`` endpoint.

.. code-block:: python
    
    import json

    import requests

    creds = "your_creds_here_but_remember_to_never_commit_secrets"

    resp = requests.post(
        "https://mnhs-rma-prod.uc.r.appspot.com/auth/sign-in-with-api-creds", 
        data=json.dumps({"apiCreds": creds})
    )
    access_token = json.loads(resp.content)["accessToken"]

Then, on any subsequent requests to the API, pass your "access token" in the 
header as a Bearer token:

.. code-block:: python

    resp = requests.get(
        "https://mnhs-rma-prod.uc.r.appspot.com/census/count",
        headers={"Authorization": f"Bearer {access_token}"},
    )

Access tokens expire after 30 minutes, so if your session lasts longer than
that you'll need to refresh your token by repeating the ``POST`` to the 
``/auth/sign-in-with-api-creds`` endpoint. If your requests start returning 
401 responses, then you need to refresh your token. You can also check whether 
your access token is expired or not at this endpoint:

.. code-block:: python

    resp = requests.put(
        "https://mnhs-rma-prod.uc.r.appspot.com/auth/verify-access-token",
        data=json.dumps({"token": access_token})
    )
    # Will be a simple boolean:
    check = json.loads(resp.content)
    if not check:
        # Do the refresh
        pass