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:
- Very few Indian students have access to .edu email accounts
- 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 |
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. |