Click or drag to resize
ParaPlan Logo

How To Login

This document will highlight how to obtain a key to connect to the ParaPlan API.

Request a key by passing in the user's email address, their password encoded in SHA-512 and the calling app name. This will give you back a token and a restURL.

Note Note

The restURL may change, so be sure not to hard code it.

Sign future requests with the key and the same device name. This token is good for 12 hours. All results have a tokenExists and tokenIsValid bool property that can be queried for token status. You can also refresh a token without making the user login.

Postman is good for API testing (https://www.getpostman.com)

Usage
Note Note

When authenticating with username and password, the API will return token to sign calls AND a restURL. Use the restURL to prefix future calls.

Caution note Caution

Be sure to pass in DeviceType to receive push notifications. Valid values are APN (iOS) and FCM (Android).

How to get a key:

  1. Send a GET request to:Login(String, String, String, String, String, String, String)

    Login
    1var loginUrl = $"https://aws.engraph.com/ParaPlanREST/UserService/Login?UserName={email}&Password={password}&Device=connect-web&Version=0.1&DeviceToken=none&UTCOffset=-4&DeviceType=APN";
    2using (WebClient client = new WebClient())
    3{
    4    string s = client.DownloadString(loginUrl);
    5    var token = JsonConvert.DeserializeObject<UserToken>(s);
    6
    7}
  2. It will return back an object (UserToken) with information about your login that will look like:

    json
    {
      "errorMessage": "",
      "success": true,
      "tokenExists": true,
      "tokenIsValid": true,
      "AssignedRoute": "DEMO-1",
      "AssignedTimes": "8:00 AM - 1:09 PM",
      "AssignedTripCount": "6 Trips",
      "AssignedVehicle": "2007 Trek Pilot 1.2 (311)",
      "AvailableFundingSources": null,
      "CanCallClients": false,
      "CanCancel": true,
      "CanScheduleTrips": true,
      "CanViewVehicles": true,
      "ClientCanRequestTrips": true,
      "ClientID": 19466,
      "CollectGPS": false,
      "CopayPaymentTypes": [
        "Not Cash",
        "Voucher",
        "Ticket",
        "Credit Card"
      ],
      "CurrentDriverBreakID": 0,
      "DatabaseID": 0,
      "DefaultPaymentType": "Voucher",
      "DeviceToken": null,
      "Key": "ca4369c1-1dca-4902-b8d5-e32235b339ff",
      "LocalDriverID": 157,
      "Name": "Tim Hibbard",
      "PPPAccess": 1,
      "ProviderCanRequestTrips": false,
      "ProviderCanViewClientDetails": false,
      "ProviderPrograms": "",
      "ProviderProgramsList": null,
      "RESTUrl": "https://aws.engraph.com/ParaPlanREST/",
      "UserId": 294,
      "UserType": 0
    }
    Note Note

    PPPAccess determines if a user can have access to the ParaPlan Passenger Portal.

    Possible values are:
    0 = Not Registered
    1 = Is registered and has access
    2 = User is blocked from Portal
    3 = User has failed validation and needs dispatcher intervention

    Note Note

    UserType indicates the type of user logging in.

    Possible values are:
    0 = Driver
    1 = Mobility Manager
    2 = Rider

How to refresh a token

  • If an API call returns tokenIsValid == false and tokenExists == true, then you can refresh the token.

    Send a GET request to:RefreshToken(String, String, String, String)

    Refresh
    1var refreshUrl = $"{storedRESTUrl}/UserService/RefreshToken?Token={expiredToken}&UserName={email}&Password={SHA-512_encoded_password}&Device={App_Name}";
    2using (WebClient client = new WebClient())
    3{
    4    string newToken = client.DownloadString(refreshUrl);
    5
    6}
Tip Tip

The JSON needs to have the key in double quotes. So "apptTime" : value, "clientFirstName" : "Jon Smith",...

Tip Tip

Numbers do not need to be encased in quotes, but bools do. So "clientInWC" : "false" ... (https://jsonlint.com is good for json validation)

Tip Tip

nil is not an accepted value. Use null instead.