Notes for Superusers


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)


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 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 Integration.

CLI automation (curl)

Service request example

As a simple example we will list existing images

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.

    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).

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": ""}},
        {"id": 2, "file": {"url": ""}}