Skip to content

Authentication

For authentication, the ProGlove API acquires a JWT access token to allow you to make REST requests to the API. To get this token, you need user credentials like User Name, Password, and a Customer ID.

Getting 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

If successful, the REST response contains a well formed JSON:

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

To prepare for the next step, extract the field user_pool_client_id.

Logging in and Getting an Access Token

The ProGlove Cloud system uses AWS Cognito to authenticate users.

To log in:

  1. POST a request with your credentials and the User Pool Client ID as a JSON payload.
  2. Set the following HTTP header fields as below:

    Content-Type = application/x-amz-json-1.1 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"
      }
    }
  1. When done, post this to:

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

If successful, the HTTP response holds a JSON AuthenticationResult object with the neccessary Access Token for the specified duration.

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

The string value IdToken is used to make REST requests from the ProGlove Cloud 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 headers:
    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.