API
The Route2 API is a RESTful web service that provides programmatic access to Route2 functionality. It is intended for use by developers who want to integrate Route2 with own applications.
Schema
See full schema documentation.
Authorization
In order to make an authorized API request one should first obtain id_token from AWS Cognito.
I. Registration of a new user
At the start of registration process a user will receive an email with a temporary password. It will be required to provide new password on the first login on the Route2 page.
After that user will be asked to set up Multi-Factor Authentication (MFA) using TOTP. UI will display QR code that can be scanned with an authenticator app (e.x. Google Authenticator) and will also provide the TOTP secret key - below the QR.
Make sure to store the TOTP secret key in a safe place. It will be needed in authorization process and this is the only moment when user can get it.
II. Obtaining id token
It's best to use AWS Cognito client or your preferred Cognito library (e.x. pycognito). Making direct HTTPS requests is also possible but more complex.
Ask the administrator for the right USER_POOL_ID and CLIENT_ID to initialize the Cognito client.
Make an "authenticate user" call using user's name and password.
It should respond with SOFTWARE_TOKEN_MFA challenge, asking to provide TOTP code.
Make a "respond to auth challenge" call using:
- ChallengeName="SOFTWARE_TOKEN_MFA"
- ChallengeResponses={ "USERNAME": "<user_email>", "SOFTWARE_TOKEN_MFA_CODE": "<totp_code>" }
- Session="<session_from_previous_response>"
Where <totp_code> is a code generated with your preferred library (e.x. pyopt) implementing TOTP algorithm (RFC 6238) and user's TOTP secret key.
The response will contain id_token that should be used in the Authorization header for subsequent API calls.