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

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.

Make a POST request to:

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

Set the following HTTP Headers as below:

Content-Type:
```
application/x-amz-json-1.1
```

X-Amz-Target:

AWSCognitoIdentityProviderService.InitiateAuth

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:

Make a POST request to:

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

Set the following HTTP Headers as below:

Content-Type:
```
application/x-amz-json-1.1
```

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:

ProGlove Documentation