Mobile Apps

Mar 20, 2015

Mobile Apps

Integrating with Validic Connect as a mobile app is the same as for a web app with the exception of authorization. Authorization for a mobile app is a Pincode based process rather than a signature based one.

Authorization User Experience for Mobile Apps

The user experience for authorization with a mobile app includes the following steps:

  1. A third-party application presents a user the Validic Marketplace of apps with the option to connect them to their application.
  2. Upon clicking “Connect”, the user is presented a PIN code and told to input that PIN within the mobile app.
  3. The user navigates to your app’s Input Pin Page and enters the PIN
  4. A correct submission will confirm the user’s connection between their account and the “consumer’s” application.
  5. An incorrect submission asks the user to resubmit the correct PIN or generate a new PIN in the “consumer” app.

Handling Authorization for New Users

The Input Pin Page should be a page within your mobile app only available to logged in users. Upon input of the Pincode your mobile app will only need to make a single POST to Validic to confirm the authorization and receive Validic credentials on behalf of that user:

POST https://api.validic.com/v1/organizations/{ORGANIZATION_ID}/authorization/new_user
-H 'Content-Type: application/json'
 {
   "user": {
     "uid": "{YOUR_USER_ID}"
   },
 "pin": "{PINCODE}",
 "access_token": "{ORGANIZATION_ACCESS_TOKEN}"
 }

Note: The UID must be unique to that user in your system and cannot be an email. That response will look like:

 201
 {
   "code": 201,
   "message": "Authorized",
   "user": {
     "_id": "{USER_ID}",
     "uid": "{YOUR_USER_UID}",
     "access_token": "{USER_ACCESS_TOKEN}"
   },
   "application": "{THIRD_PARTY_APPLICATION_NAME}"
 }

For those familiar with Validic’s User Provisioning process, this request has provisioned a user in Validic with the uid you send in the POST request.

Similar to web based applications, you should manage the “consumer” application that are synced to your user. All other practices related to managing user generated data remain the same as with a web app (see previous sections for more).

Handling an Invalid Pincode Response

When an Authorization request sent to Validic fails, a 401 error response will be returned by Validic. In this case, you must handle the response in your application properly for the user to know that the provided pincode was invalid or expired. Typically, this is done by providing an error notice in your application’s Input Pin Page. Pincodes are active for 30 minutes once generated by the user. In case of an expired pincode, you must inform your user to return to the App Marketplace to regenerate a new pincode. Below is what a typical authorization with 401 response will look like:

POST https://api.validic.com/v1/organizations/ORGANIZATION_ID/authorization
-H 'Content-Type: application/json'
{
  "access_token": "{USER_ACCESS_TOKEN}",
  "pin": "{PINCODE}"
}

That response will look like this:

{
  "code": 401,
  "message": "expired pin or bad request"
}

View More >