Version 0.5.5

This version introduces resource and data permissions. Allowing for a better control of the data allowed to be read or updated using tokens.

Introduction

StudentConnect is a student verification platform for websites and mobile applications. It provides a REST JSON API easy to consume on any device.
The platform authenticates and verifies students across hundreds of universities in the UK and other countries, providing clients with profiles, data and insights, allowing you to increase your audience and customer base.

Audience

This document is primarily for website owners with a technical background or part of the technical support staff.

The verification flow

Similar to other user verification methods (e.g. Facebook or Google), StudentConnect API allows you to sign up or log in users using a token generated on your side.
StudentConnect API verification flow

The user land on your website and would like to sign in. They click on the "Sign in with StudentConnect" button and get redirected to the StudentConnect Verification page.
StudentConnect will check if the user is already logged in or not. If not, they'll get asked to verify their student account. Once the user is verified StudentConnect will ask them to allow the website access to their data. In case they respond "yes" they get redirected back to the website allowing the client site to access the data. If they respond "no" they will get redirected to the website but, the the client website won't be allowed access to the profile data. StudentConnect API verification flow

Requirements

When integrating the platform with a website you are required to provide us at least one HTTPS endpoint for the signup success page. This page will receive the data from our API upon successful signup and it’s very important to secure the data in transmit.

When integrating with a mobile app you can use app specific URIs, but wen we don’t allow plain HTTP endpoints for landing pages.

Launching the platform on your website or mobile app should be made in conjunction with a discount or coupon campaign, in a way that allows new users to receive discounts and special offers, with a minimum of effort.
Terms and conditions of your campaign are also mandatory and should be present via a link or inside a text block, either on the sign up page or on the landing page.

Example of previously approved discount campaigns:
  • verified students can purchase products at a lower price
  • verified students automatically receive a discount code
  • verified students automatically get their cart value discounted
  • micro-site allowing verified students to enter a competition
You may choose to run different campaigns, however they need to be approved by our team before going live.

Buttons

To enable sign in with student connect on your website or mobile app, you can use one of the following buttons:

Branding

Depending on your subscription level you may customize the look&feel of the signup process. Available options include custom css and custom templates.
For more details please get in touch.

Pricing

Pricing is made on a per-lead basis. Each successful sign up is considered a lead. For more details please get in touch with our sales team .

Integration

You may integrate the platform in various ways. The easiest way is to host a form on your website or app and submit the data directly to the API’s /signin endpoint. All you need is a valid token (see below) sent as token parameter. The API will take care of the authentication and data capture and, upon verification, will send the user back to your website sign up landing page. However this is not recommended as it's prone to errors and tokens expire in a relatively short period.

The best way to integrate is using a client. You can download the latest version of our official PHP client library from GitHub . A client library allows you to achieve a tighter integration, generate tokens automatically and offer a better user experience.

Authentication

When you successfully sign up for an api key, you will receive a test endpoint for API calls, and your client credentials: an App Key and App Secret.

The App Key and App Secret need to be stored in a secure location or file on your server, forbidden from public access. Also, if you have multiple apps or websites we strongly advise requesting a different set of credentials for each.

Currently the API supports two forms of authentication: signature and token. Your client may use one or the other, but not both. Signatures are generated on the client side using HMAC with the SHA256 algorithm.
Usually you validate a signature in order to obtain a token.

Tokens are required when you need to verify students through your application.
Once a student signs up or logs in using the token your client provided, that user is set as the current profile for any api calls using the token.

A typical authorization flow follows these steps:
  • create a signature
  • send a request to the api, with the signature in headers
  • save the api token locally
Once you have the token you can use it for future api calls.
Tokens also have an validation period and may not be accepted by the API after they expire. In order to avoid using expired tokens, check the expiry time in the API response.

Additionally access to resources is limited with permissions. Currently permissions are allocated on an application-basis when you sign up and cannot be changed.

Resources

The REST API allows you to authenticate users and request profiles data. Depending on your subscription level you could also request profile insights and data about academic institutions available on the platform.
Below is a list of resources currently available.

/authorize

Using this resource you can validate your signature and generate a new token for your client.
In order to obtain a new token, you need to include a valid signature in the the Authorization header, alongside an X-Timestamp and optionally an X-Nonce header. The response contains data about the token including the token expiry time.
In the example below, the signature is generated by the client library.

The response contains the token value (string), a list of permissions granted to the token, token creation time and token expiration time.

Request

POST /authorize

Response

{
  "code": 201,
  "status": "success",
  "data": {
    "token": "zTVBTONKfRwLrwmTcgJeZyRvO29v3f8YyzxphLigDxtyOFBno",
    "permissions": {
      "GET/": {
        "as": "Subscriber",
        "with": "*"
      },
      "GET/token": {
        "as": "Contributor",
        "with": "*"
      },
      "GET/client": {
        "as": "Subscriber",
        "with": {
          "logo": true,
          "meta": {
            "ui": true,
            "endpoints": true
          },
          "domain": true,
          "username": true,
          "organization": true
        }
      },
      "GET/signin": {
        "as": "Subscriber",
        "with": "*"
      },
      "GET/profile": {
        "as": "Subscriber",
        "with": {
          "meta": {
            "emails": true,
            "phones": true
          },
          "email": true,
          "avatar": true,
          "address": true,
          "country": true,
          "language": true,
          "birthdate": true,
          "last_name": true,
          "first_name": true
        }
      },
      "POST/signin": {
        "as": "Contributor",
        "with": "*"
      },
      "POST/tokens": {
        "as": "Contributor",
        "with": "*"
      },
      "POST/authorize": {
        "as": "Contributor",
        "with": "*"
      },
      "GET/profile/affiliations": {
        "as": "Subscriber",
        "with": {
          "course": true,
          "affiliation": true,
          "graduation_year": true
        }
      }
    },
    "created_at": 1462360710,
    "expires_at": 1462447110
  },
  "meta": {
    "cached": false
  }
}

Example

<?php

require_once (__DIR__ . '/vendor/autoload.php');

define('ENDPOINT', 'https://api.endpoint');
define('KEY'     , 'your-app-key');
define('SECRET'  , 'your-app-secret');

use StudentConnect\API\Client\Client;
use StudentConnect\API\Client\Exceptions\ClientException;

try{

    $Client = new Client(ENDPOINT, KEY, SECRET);
    $Client->authorize();

    //get the token object
    $Token = $Client->getToken();

    //we're using PHP's internal APC store, but any session or cache storage will do
    apc_store('api_token', $Token, 86400);

}
catch (ClientException $e){

    //something went wrong
    die("Ops! Client authorization failed: " . $e->getMessage());

}

/signin

Generates the sign in URL for a user, based on data sent by the client. E.g. if the data contains only valid email the url will point to the email authentication gateway.
Optionally the client can tell the API to automatically redirect to the appropriate endpoint using the forward parameter.

Parameters

Name Type Default  
forward boolean true (optional) forward the request to the sign in endpoint
with_token boolean false (optional) include the token parameter in the endpoint url
email string null (optional) user email
password string null (optional) user password
entity_id string null (optional) institution entity id
institution_id integer null (optional) institution id

Request

POST /signin

forward=0
with_token=0
email=someone@somewhere.com

Response

{
  "code": 200,
  "status": "success",
  "data": {
    "endpoint": "https://email-signin.api.endpoint",
    "method": "email",
    "uri": "https://email-signin.api.endpoint",
    "with_token": false
  },
  "meta": {
    "expires_at": 1462361310,
    "cached": false
  }
}

Example

<?php

require_once (__DIR__ . '/vendor/autoload.php');

//our client object previously created
global $Client;

use StudentConnect\API\Client\Client;
use StudentConnect\API\Client\Exceptions\ClientException;

try{

    $uri = $Client->generateSignInURI([
        //additionally you could add here email, institution_id, first_name, last_name or other
        //valuable data for generating the sign in URI
    ], FALSE);


    //-- output the sign in form --//
    ?>

    <form method="post" target="_self" action="<?php echo $uri; ?>">

        <?php

        //tokenize the form, so we have our token sent with the request
        $Client->tokenizeForm();

        ?>

        <!-- the sign in button -->
        <button class="btn btn-lg btn-info" type="submit">
            Verify your student account &rarr;
        </button>
        <!-- the sign in button -->

    </form>

    <?php
    //-- output the sign in form --//

}
catch (ClientException $e){

    //something went wrong
    die("Ops! We couldn't generate the signin uri because: " . $e->getMessage());

}

/profile

Get current profile data
Depending if the token has been granted access, the client may receive a full profile or an anonymous one.
A full profile contains first name, last name and real email address. An anonymous one contains a garbled email address only.
To distinguish between the two cases use the is_anonymous field in the API response object.

Request

GET /profile

Response

{
  "code": 200,
  "status": "success",
  "data": {
    "email": "lgf456@university.ac.uk",
    "avatar": "https://www.gravatar.com/avatar/cddf0cfaffja797a8c3db7b5eee1eba9",
    "first_name": "Louis",
    "last_name": "Woodward",
    "gender": "male",
    "birthdate": "1990-05-31",
    "phone": "07280 195 622",
    "country": "GB",
    "language": "en",
    "address": "58 Bullwood Rd ST CROSS SOUTH ELMHAM IP20 4XB",
    "emails": {
      "university": "lgf456@university.ac.uk",
      "contact": "lwood990@hotmail.co.uk"
    },
    "devices": [
        "Mac OS X",
        "Android"
    ],
    "interests": [
      "headphones", "beats", "apple", "nus-card"
    ],
    "verified_at": 1461834590,
    "verified_until": 1493370590,
    "is_anonymous": false
  },
  "meta": {
    "cached": false
  }
}

Code

<?php

require_once (__DIR__ . '/vendor/autoload.php');

//our client object previously created
global $Client;

use StudentConnect\API\Client\Client;
use StudentConnect\API\Client\Exceptions\ClientException;

//init the client with the token
$Token = apc_fetch('api_token');
$Client->setToken($Token);

try{

    //retrieve user profile
    $profile = $Client->getCurrentProfile();

    //see what we've got
    var_dump($profile);

}
catch (ClientException $e){

    //something went wrong
    die("Ops! We couldn't get the current profile because: " . $e->getMessage());

}

/profile/affiliations

Retrieve current profile affiliations with various institutions.

Request

GET /profile/affiliations

Response

{
  "code": 200,
  "status": "success",
  "data": [
    {
      "institution_id": 273,
      "name": "University of Cambridge",
      "logo": "https://www.cam.ac.uk/logo.jpg",
      "affiliation": "student",
      "course": "Chemical Engineering",
      "graduation_year": 2010
    },
    {
      "institution_id": 985,
      "name": "University of Manchester",
      "logo": "https://www.manchester.ac.uk/logo.png",
      "affiliation": "other",
      "course": "Philosophy",
      "graduation_year": 2006
    },
    {
      "institution_id": 273,
      "name": "University of Cambridge",
      "logo": "https://www.cam.ac.uk/logo.jpg",
      "affiliation": "library-walk-in",
      "course": null,
      "graduation_year": 2020
    },
    {
      "institution_id": 1353,
      "name": "Imperial College London",
      "logo": "https://www.imperial.ac.uk/logo.jpg",
      "affiliation": "staff",
      "course": "Mathematics",
      "graduation_year": 2019
    }
  ],
  "meta": {
    "cached": false
  }
}

Example

<?php

require_once (__DIR__ . '/vendor/autoload.php');

//our client object previously created
global $Client;

use StudentConnect\API\Client\Client;
use StudentConnect\API\Client\Exceptions\ClientException;

//init the client with the token
$Token = apc_fetch('api_token');
$Client->setToken($Token);

try{

    //retrieve user profile
    $profile = $Client->get('/profile/affiliations');

    //see what we've got
    var_dump($profile);

}
catch (ClientException $e){

    //something went wrong
    die("Ops! We couldn't get the profile affiliations: " . $e->getMessage());

}

Clients

Currently our official PHP Client is available on GitHub . Follow the link for installation and usage details.

Errors

400 The client sent a malformed request. Most likely, the Authorization header is missing or contains an invalid signature.
403 The client does not met permissions to execute the request.
404 The resource requested does not exists. Check the path and try again.
500 API Error. Something gone wrong and the server could not satisfy your request.

Support & Contact details

You may contact us at james@studentmoneysaver.co.uk or by phone at +44 (0) 207 183 4673.