NAV
javascript

Introduction

Welcome to the Student Identify developer guide.
Student Identify is a service to enable companies to digitally verify the student status of their customers. The concept of student benefits is global and today’s smart businesses understand the value of running special incentive programs for students. However, companies find it cumbersome to verify the eligibility of these student customers because:

  1. Very few Indian students have access to .edu email accounts
  2. India doesn’t have an authoritative database of students accessible by companies

Using Student Identify, companies can enable their customers to upload their student documents onto their platforms and verify their eligibility. These documents are sent to us for verification and we conduct checks using technology as well as by our team of manual experts. Student Identify is the first solution for Student Verification at scale, built especially for the Indian market. The service is provided and developed by the team behind Frapp.in, registered under Wynaut Webventures Private Limited.

App Creation

Student Identify provides a developer console for creation of the Apps under the OAuth process (currently under development). A developer after getting verified has the right to create multiple apps. Apps are synonymous to the “client” as defined in the RFC 6749 standard. Multiple apps can be created to satisfy use case of segregating users on per project basis. The following is the information required at the time of creating an app.

App Structure

Field Type Description
name String Name of the app
icon String (url) Icon for the app
description String Description of the app
privacyPolicyUrl String (url) Privacy Policy url required to be shown to users
redirectUris Array (url) An array of redirect uris
originUri String (url) Uri for the origin page of the integration
clientId String System generated unique public id of the app
clientSecret String System generated secret for the app
showPending Boolean Handles showing pending user confirmation screen
showVerified Boolean Handles showing verified user confirmation screen
showDenied Boolean Handles showing denied user confirmation screen

After the creation of the app a clientId and clientSecret is generated for the app. Both of these parameters are required to complete the request for user access in the OAuth process.

User Entity

The Student Identify platform functions by capturing user information and saving it in a user object. The collected user data is used for user verification. User data is shared using OAuth process. The following section details the user entity.

Field Type Description
firstname String User’s firstname
lastname String User’s lastname
college String User’s college
status String Assumes values pending, verified or denied
verifiedUpto String (date) Date until which user is verified 
//Example User Object
{
    firstname:"John",
    lastname:"Doe",
    college:"Princeton University",
    status:"verified",
    verifiedUpto:"2020-02-19T18:30:00.000Z"
}

OAuth Scopes for the user

The user attributes are limited by scopes as per the OAuth standard. The following table mentions all the scopes available for use. Both the statuses have been accepted as the default and can be used for fetching user info.

Scope Description
status Fetch the status of the user
basic_info Fetch the firstname, lastname
college Fetch the user’s college
verified_upto Fetch the verifiedUpto date

The scopes status and basic_info are enabled by default. Other scopes are enabled after a request to hello@studentidentify.com.

Api Integration

The integration of Student Identify for student verification can be done simply by following a manual authorization code flow as per OAuth v2.0. The following sections describe the flow in detail.

Api Url for integration

After creation of the app, the developers would be given a link,which would be used for integration in your website. You can check the demo here.

//Example of an integration url
https://app.studentidentify.com/?oauth=true&clientId=3da5853755bce683bd069c38fbbef3443765b142&response_type=code&redirect_uri=http://13.250.183.221:4500/&scope=status&state=demoapp

The following is required as the part of the url

Field Description
oauth defaults to true (required)
clientId The clientId for the app
response_type As per OAuth Authorization code grant type, defaults to code
redirect_uri The url for redirection
scope comma separated scopes
state use of this field is upon developer discretion

OAuth Flow

Under the ambit of OAuth, we can find multiple grant types. Discussion on different grant types and their functioning is beyond the scope of this documentation. The user can refer the RFC 6749 standard for further investigation. The Student Identify platform employs the Authorization Code grant type. In the Authorization Code grant type, an authorization code is obtained from an authorization server. The code acts as intermediate token for the resource seeking server to fetch an access token from a resource server against a user record. Such an access token can be used to fetch user record from the resource server. The process is elaborated in the following sections.

Code Generation

After getting the url from the developer tool mentioned in the section above, the url has to be embedded in the page of concern on the third party website. It should be noted that the page url should be same as the value of the originUri for the app under use. The url can be invoked with the help of popup or can be just redirected to, too. The url opens up a Student Identify form meant for collecting user info. After the user inputs all the information the app redirects to the redirectUri mentioned in the url. The reirectUri has to be among the ones present in the app object under the redirectUris field. The redirectUri is redirected with code and state as the url query parameters.

Access Token Generation

After the flow has reached to your server after the redirection, you can call the Student Identify api for access token generation

HTTP Request

GET https://api.studentidentify.com/oauth/token

Query Parameters

Parameter Description
grant_type defaults to authorization_code
code authorization code
client_id App client id
client_secret App client secret

Response of the Api

Field Description
accessToken AccessToken for concerned user
expiresAt Expiry time for the accessToken
scope Scope for user object information
clientId App client id 
var request= require('request');
request.get({
    url:'https://api.studentidentify.com/oauth/token',
    qs:
    {
        grant_type:"authorization_code",
        code:"XXXXXX",
        client_id:"XXXXXX",
        client_secret:"XXXXXX"
    }
});

The above api call returns JSON structured like this

{
    "accessToken":"XXXXXX",
    "expiresAt":"2020-02-19T18:30:00.000Z",
    "scope": "status,basic_info",
    "clientId":"XXXXXX"
}

The accessToken received can now be used to gain access of the user’s information based on the scoped granted for the user.

Use of Access Token

The accessToken received as a part of the previous operation can be used to get user information. The required api call is mentioned below.

HTTP Request

GET https://api.studentidentify.com/user/getUser

Query Parameters

Parameter Description
accessToken AccessToken for concerned user

Response of the Api

Field Description
status Status of the user
firstname User’s firstname
lastname User’s lastname
email User’s email
verifiedUpto User’s expiry of verified status
siid User’s StudentIdentify public id 
var request= require('request');
request.get({
    url:'https://api.studentidentify.com/user/getUser',
    qs:
    {
        accessToken:"XXXXXX"
    }
});

The above api call returns JSON structured like this

{
    "status":"verified",
    "firstname":"John",
    "lastname":"Doe",
    "email":"johndoe@gmail.com",
    "siid":"XXXXXXX"
}

Postback Url (Webhook)

The postback url feature is meant to provide a callback when a user status changes from pending to verified or denied. The system sends a POST request with a JSON payload having concerned user’s object, scoped by the allowed scopes for your app. This gives you real-time updates in case of manual verification. The postback url is a property of your app.

HTTP Request

POST https://your_postback_url

Body Parameters

Parameter Description
user properties list of user properties

Errors

The Student Identify API uses the following error codes:

Error Code Meaning
400 Bad Request – The request has incorrect call
401 Unauthorized – Supplied credentials are wrong
403 Forbidden – The requested api is hidden
404 Not Found – The requested resource could not be found
429 Too Many Requests – Amount of requests are too many!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.
javascript