Python

See https://pypi.org/project/scribeauth/ for the instructions on how to get a token.

Node.js

See https://www.npmjs.com/package/@scribelabsai/auth or

npm install @scribelabsai/auth

Raw API calls

Most calls to Scribe's API require authentication and authorization. This guide details the steps to follow.

You first need a Scribe account and a client ID. Both can be requested at support[atsign]scribelabs[dotsign]ai or through Intercom on https://platform.scribelabs.ai if you already have a Scribe account.

Flow

If you never have accessed your Scribe account, it probably still contains the temporary password we generated for you. You can change it directly on the platform or following these steps. You won't be able to access anything else until the temporary password has been changed.

---

Authenticating for the first time

• Getting challenge

Send a request with the following format:

curl -X POST https://cognito-idp.eu-west-2.amazonaws.com/ \
  -H 'Content-Type: application/x-amz-json-1.1' \
  -H 'X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth' \
  -d '{
    "AuthFlow": "USER_PASSWORD_AUTH",
    "ClientId": "{client_id}",
    "AuthParameters": {
      "USERNAME": "{username}",
      "PASSWORD": "{password}"
      }
    }'

The response will look like this:

{
  "ChallengeName": "NEW_PASSWORD_REQUIRED",
  "Session": "string",
  "ChallengeParameters": { 
    "string" : "string" 
  }
}

• Respond to challenge

Get Session and ChallengeParameters from the response. Get requiredAttributes and USER_ID_FOR_SRP from ChallengeParameters.

Send a request with the following format:

curl -X POST https://cognito-idp.eu-west-2.amazonaws.com/ \
  -H 'Content-Type: application/x-amz-json-1.1' \
  -H 'X-Amz-Target: AWSCognitoIdentityProviderService.RespondToAuthChallenge' \
  -d '{
    "ChallengeName": "NEW_PASSWORD_REQUIRED",
    "ChallengeResponses": {
      "USER_ID_FOR_SRP": "{user_id_for_srp}",
      "requiredAttributes": "{required_attributes}",
      "USERNAME": "{username}",
      "NEW_PASSWORD": "{new_password}"
    },
    "ClientId": "{client_id}",
    "Session": "{session}"
  }'

The response will look like this:

{
  "AuthenticationResult": { 
    "AccessToken": "string",
    "ExpiresIn": number,
    "IdToken": "string",
    "NewDeviceMetadata": { 
      "DeviceGroupKey": "string",
      "DeviceKey": "string"
    },
    "RefreshToken": "string",
    "TokenType": "string"
  },
  "ChallengeName": "string",
  "ChallengeParameters": { 
    "string" : "string" 
  },
  "Session": "string"
}

---

Change Password

Send a request with the following format:

curl -X POST https://cognito-idp.eu-west-2.amazonaws.com/ \
  -H 'Content-Type: application/x-amz-json-1.1' \
  -H 'X-Amz-Target: AWSCognitoIdentityProviderService.ChangePassword' \
  -d '{
    "AccessToken": "{access_token}",
    "PreviousPassword": "{old_password}",
    "ProposedPassword": "{new_password}"
  }'

Response:

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

---

Forgot Password

• Getting a confirmationCode

A message will be sent to the user email with a confirmation code that is required to change the user's password.

Send a request with the following format:

curl -X POST https://cognito-idp.eu-west-2.amazonaws.com/ \
  -H 'Content-Type: application/x-amz-json-1.1' \
  -H 'X-Amz-Target: AWSCognitoIdentityProviderService.ForgotPassword' \
  -d '{
    "ClientId": "{client_id}",
    "Username": "{username}"
  }'

The response will look like this:

{
  "CodeDeliveryDetails": { 
    "AttributeName": "string",
    "DeliveryMedium": "string",
    "Destination": "string"
  }
}

• Using confirmationCode

Send a request with the following format:

curl -X POST https://cognito-idp.eu-west-2.amazonaws.com/ \
  -H 'Content-Type: application/x-amz-json-1.1' \
  -H 'X-Amz-Target: AWSCognitoIdentityProviderService.ConfirmForgotPassword' \
  -d '{
    "ClientId": "{client_id}",
    "Username": "{username}",
    "ConfirmationCode": "{confirmation_code}",
    "Password": "{new_password}"
  }'

Response:

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

---

Get tokens

With username and password:

Send a request with the following format:

curl -X POST https://cognito-idp.eu-west-2.amazonaws.com/ \
  -H 'Content-Type: application/x-amz-json-1.1' \
  -H 'X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth' \
  -d '{
    "AuthFlow": "USER_PASSWORD_AUTH",
    "ClientId": "{client_id}",
    "AuthParameters": {
      "USERNAME": "{username}",
      "PASSWORD": "{password}"
    }
  }'

The response will look like this:

{
  "AuthenticationResult": { 
    "AccessToken": "string",
    "ExpiresIn": number,
    "IdToken": "string",
    "NewDeviceMetadata": { 
      "DeviceGroupKey": "string",
      "DeviceKey": "string"
    },
    "RefreshToken": "string",
    "TokenType": "string"
  },
  "ChallengeName": "string",
  "ChallengeParameters": { 
    "string" : "string" 
  },
  "Session": "string"
}

With refreshToken:

Send a request with the following format:

curl -X POST https://cognito-idp.eu-west-2.amazonaws.com/ \
  -H 'Content-Type: application/x-amz-json-1.1' \
  -H 'X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth' \
  -d '{
    "AuthFlow": "REFRESH_TOKEN",
    "ClientId": "{client_id}",
    "AuthParameters": {
      "REFRESH_TOKEN": "{refresh_token}"
    }
  }'

The response will look like this:

{
  "AuthenticationResult": { 
    "AccessToken": "string",
    "ExpiresIn": number,
    "IdToken": "string",
    "NewDeviceMetadata": { 
      "DeviceGroupKey": "string",
      "DeviceKey": "string"
    },
    "RefreshToken": "string",
    "TokenType": "string"
  },
  "ChallengeName": "string",
  "ChallengeParameters": { 
    "string" : "string" 
  },
  "Session": "string"
}

---

Revoke Refresh Token

Send a request with the following format:

curl -X POST https://cognito-idp.eu-west-2.amazonaws.com/ \
  -H 'Content-Type: application/x-amz-json-1.1' \
  -H 'X-Amz-Target: AWSCognitoIdentityProviderService.RevokeToken' \
  -d '{
    "ClientId": "{client_id}",
    "Token": "{refresh_token}"
  }'

Response:

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

---

Possible Exceptions

InternalErrorException

This exception is thrown when Amazon Cognito encounters an internal error.

HTTP Status Code: 500

---

InvalidParameterException

This exception is thrown when the Amazon Cognito service encounters an invalid parameter.

HTTP Status Code: 400

---

TooManyRequestsException

This exception is thrown when the user has made too many requests for a given operation. For example: Changing passwords frequently within a short time period.

HTTP Status Code: 400

---

UnauthorizedException

Exception that is thrown when the request isn't authorized.

HTTP Status Code: 400

---

Once you have the id token, use it as an Authorization header, i.e. "Authorization": "token"