==============
Authentication
==============
.. _authentication:

Authentication using JSON Web Token (JWT)
=========================================

Skykit API can be securely accessed using a JSON Web Token (JWT).

In order to access Skykit API using a JWT, a public/private RSA key pair is needed.  The key pair can be generated through various means such as the standard openssl command-line tools, demonstrated in the example section below.

Once the key pair has been generated, please send the **public** key and the email address that you wish for the key to be associated with to Skykit Support (`support@skykit.com <support@skykit.com>`_), while keeping the **private** key hidden.  Do not share your private key, as anyone possessing it may access the system on your behalf.

After the public key has been added into the system, the keys may be used to generate an access token with the following claims:

.. code-block:: javascript

   {
      "iat": <issued timestamp>,
      "exp": <expiration timestamp>,
      "iss": <email address>
   }

The token is valid between the issued and expiration times, the duration of which must not exceed one hour.

Requests may be authenticated and authorized against Skykit API by attaching the access token as the ``Authorization`` HTTP request header value prefixed by ``Bearer`` and separated by a space:

.. code-block:: html

   Authorization: Bearer <token>

A single access token can be used with any number of requests so long as the token has not expired, includes the required claims shown above, and corresponds to a public key that has been properly registered into the system.


Client Authentication Example
-----------------------------

The following example walks through the process of generating keys, signing JWTs, and making requests to Skykit API.

The code is written in Python but other languages and libraries may be used as well.

1. Install dependencies:
------------------------

.. code-block:: bash

   virtualenv venv
   source ./venv/bin/activate
   pip install python-jose requests


2. Generate keys:
-----------------

Generate a private and public key-pair using OpenSSL:

.. code-block:: bash

   openssl genrsa -out private.pem 2048
   openssl rsa -in private.pem -outform PEM -pubout -out public.pem
.. openssl rsa -in private.pem -RSAPublicKey_out -out pubkey.pem


Alternatively, generate keys in Python:

.. literalinclude:: example/generate_keys.py
   :language: python


3. Register public key:
-----------------------

Send your **public** key to Skykit Support (`support@skykit.com <support@skykit.com>`_), including the email address that you wish the key to be associated with.  Keep your **private** key safe.


4. Sign JWT:
------------

.. literalinclude:: example/sign_jwt.py
   :language: python


5. Make requests to Skykit API:
-------------------------------

.. literalinclude:: example/client.py
   :language: python


Additional resources
====================
`Learn more about JWT <https://jwt.io>`_