Notes for Superusers
====================

Credentials
-----------
To authenticate with our api a customer is given following credentials

- **service credentials**:

    - ``API_BASE_URL``: url for the api (all endpoints are relative to this)
    - ``API_KEY``: static 40 character string needed to
        - authenticate specific customer
        - authorize api access

- **admin credentials**: login information for our OAuth provider (AWS Cognito).
  Can be used to obtain tokens for admin access (with 1 hour expiration)

    - ``COGNITO_IDP``: url for our identity provider
    - ``CLIENT_ID``: oauth client id
    - ``USERNAME``: username
    - ``PASSWORD``: password (can be changed)
    - ``SECRET_HASH``: a static secret value (based on client and username)


Roles
-----
We support 3 different levels of privileges based on which credentials are supplied in ``request headers``

- **service**: used by frontend for getting real time inferences (read only access)

    - ``x-api-key: <customer-api-key>``
    - ``Authorization: None``

- **admin**: used by administration backend for managing data (e.g. modify images and collections)

    - ``x-api-key: <customer-api-key>``
    - ``Authorization: Bearer <access_token>`` with OpenID scope or ``Authorization: <id_token>``

- **superuser**: used by instyle.ai developers to manage predictor models and users

    - ``x-api-key: <superuser-api-key>``
    - ``Authorization: Bearer <superuser_access_token>`` or ``Authorization: <superuser_id_token>``
    - ``x-selected-customer: <customer>``



OpenAPI docs
------------

See how to to authorize ``Try it out`` requests from interactive OpenApi docs in section :ref:`integration`.


CLI automation (curl)
---------------------

Service request example
#######################

As a simple example we will list existing images

.. code-block:: bash

    curl \
        -X GET "${API_BASE_URL}/images" \
        -H "accept: application/json" \
        -H "x-api-key: ${API_KEY}" \
        -H "Authorization: None"

Obtaining admin token
#####################

Trying out some endpoints in OpenAPI docs will also yield snippets showing how to do the same call with ``curl``.
Here we will show how to obtain the OpenID token without using a interactive authorization widget in docs.


.. code-block:: bash

    AUTH_RESPONSE=$(
        curl \
            -X POST "${COGNITO_IDP}" \
            -sS \
            -H "X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth" \
            -H "Content-Type: application/x-amz-json-1.1" \
            -d '{
                "ClientId": "'${CLIENT_ID}'",
                "AuthFlow": "USER_PASSWORD_AUTH",
                "AuthParameters": {
                    "USERNAME": "'${USERNAME}'",
                    "PASSWORD": "'${PASSWORD}'",
                    "SECRET_HASH": "'${SECRET_HASH}'",
                    "SCOPES": "OPENID"
                }
            }'
    )

    # response is a json with multiple attributes,
    # for convenience we use following python snippet to extract id_token
    ID_TOKEN=$(echo ${AUTH_RESPONSE} | python -c "import sys, json; output = json.load(sys.stdin); assert 'AuthenticationResult' in output, output; print(output['AuthenticationResult']['IdToken'])")
    echo $ID_TOKEN

Admin request example
#####################

A simple example of admin request is adding an image.
To authorize admin request we need an OAuth ``ID_TOKEN`` from above (keep in mind it has 1 hour expiration).

.. code-block:: bash

    curl \
        -X POST "${API_BASE_URL}/images" \
        -H "accept: application/json" \
        -H "x-api-key: ${API_KEY}" \
        -H "Authorization: ${ID_TOKEN}" \
        -d '[
            {"id": 1, "file": {"url": "https://cdn.pixabay.com/photo/2016/12/06/09/31/blank-1886008__340.png"}},
            {"id": 2, "file": {"url": "https://cdn.pixabay.com/photo/2015/09/06/01/03/white-926838__340.jpg"}}
        ]'