ProGlove Documentation

Authentication

ProGlove API uses JWT (JSON Web Token) to allow you to make REST requests. 

To get the token, you need the following credentials:

  • User Name - your ProGlove Insight Webportal user name (e.g. johndoe@proglove.de)

  • Password - your ProGlove Insight Webportal password

  • Customer ID - unique ID assigned to you after a GET request.

Get the User Pool ID

To get the User Pool ID, send a GET request to the following endpoint:

$BASE_URL/auth-information?id=$YOUR_CUSTOMER_ID

Note

The BASE_URL can be be found under your User Profile information on Insight Webportal. 

To learn more, see How to get Base URL.

If successful, the REST response contains a well-formed JSON as displayed below:

{
  "region": "eu-west-1",
  "customer_id:": "...",
  "user_pool_client_id": "...",
  "user_pool_id": "..."
}

You will need the "user_pool_client_id" in the next step to get the Access Token.

Log in and get the Access Token

Insight Webportal uses AWS Cognito to authenticate users.

  1. Make a POST request to:

    https://cognito-idp.{region}.amazonaws.com/login

  2. Set the following HTTP Headers as below:

    1. Content-Type:

      application/x-amz-json-1.1

    2. X-Amz-Target:

      AWSCognitoIdentityProviderService.InitiateAuth

  3. Create a JSON object with the following format and fill in the data marked with $:

        {
      "AuthFlow": "USER_PASSWORD_AUTH",
      "ClientId": "$YOUR_USER_POOL_CLIENT_ID",
      "AuthParameters":   
      {
          "USERNAME": "$YOUR_USER_NAME",  
          "PASSWORD": "$YOUR_PASSWORD"
      }
    }

If successful, the HTTP response holds a JSON AuthenticationResult object with the necessary Access Token for the specified duration as displayed below:

    {
       "AuthenticationResult":
      {
        "AccessToken":  "...",
        "ExpiresIn":    "...",
        "IdToken":      "...", // STORE THIS TO BE USED IN SUBSEQUENT REST CALLS
        "RefreshToken": "...", // SEE "LONG-LIVED CREDENTIALS" FOR MORE INFORMATION
        "TokenType":    "..."
      },
       "ChallengeParameters": {}
    }

Use the string value IdToken  to make REST requests from the Insight Webportal resources.

Expiration

The IdToken is valid for one hour.

Error codes

HTTP error code

Reason

200

OK

400

Malformed request

Long-lived credentials

When using the API with long-running services as opposed to one-shot scripts, we recommend using a RefreshToken as the primary credential instead of Username and Password.

The RefreshToken is part of a normal response to the /login endpoint. It can be used to generate a fresh set of short-lived credentials.

To exchange a RefreshToken for a short-lived IdToken:

  1. Make a POST request to:

    https://cognito-idp.{region}.amazonaws.com/login

  2. Set the following HTTP Headers as below:

    1. Content-Type:

      application/x-amz-json-1.1

    2. X-Amz-Target:

      AWSCognitoIdentityProviderService.InitiateAuth

    The request body displays as below:

        {
      "AuthFlow": "REFRESH_TOKEN",
      "ClientId": "{user_pool_client_id}",
      "AuthParameters": {
        "REFRESH_TOKEN": "{refresh_token}"
      }
    }

The {user_pool_client_id} is the Client ID acquired in Step 1, and {refresh_token} is your refresh token.

As this call uses the same endpoint as the initial Login call, the only difference in the response body is that, in this case, it does not return a RefreshToken.

In this section: