Skip to main content
This is our deprecated API. Return to the latest version here.

​
Roles

​
The Third-Party Application: “Client”

The client is the application that is attempting to get access to the user’s account. It needs to get permission from the user before it can do so.

​
The API: “Resource Server”

The resource server is the API server used to access the user’s information.

​
The user: “Resource Owner”

The resource owner is the person who is giving access to some portion of their account.

​
Creating an App

Before you can begin the OAuth process, you must first register a new app with the service. When registering a new app, you usually register basic information such as application name, website, a logo, etc. In addition, you must register a redirect URI to be used for redirecting users to for web server, browser-based, or mobile apps. If you wish to register a new app please get in touch with your account manager or contact hello@studentbeans.com.

​
Minimum Requirements

In order for us to create a new app, we require the following information:
  • App Name
  • Redirect URI
  • Terms and Conditions URL
  • Privacy Policy URL

​
Redirect URIs

The service will only redirect users to a registered URI, which helps prevent some attacks. Any HTTP redirect URIs must be protected with TLS security, so the service will only redirect to URIs beginning with “https”. This prevents tokens from being intercepted during the authorization process.

​
Client ID and Secret

After registering your app, you will receive a client ID and a client secret. The client ID is considered public information, and is used to build login URLs, or included in Javascript source code on a page. The client secret must be kept confidential. If a deployed app cannot keep the secret confidential, such as Javascript or native apps, then the secret is not used. ##Authorization The first step of OAuth 2 is to get authorization from the user. For browser-based or mobile apps, this is usually accomplished by displaying an interface provided by the service to the user. OAuth 2 provides several “grant types” for different use cases. We are currently supporting the Authorization Code grant type for apps running on a web server.

​
Web Server Apps

Web server apps are the most common type of application you encounter when dealing with OAuth servers. Web apps are written in a server-side language and run on a server where the source code of the application is not available to the public.

​
Authorization

Create a “Log In” link sending the user to: 
 GET https://accounts.studentbeans.com/oauth/authorize?client_id=CLIENT_ID\
&redirect_uri=REDIRECT_URI&response_type=code&country=COUNTRY_CODE
country is uk for United Kingdom and ISO 3166 standard two letter country code otherwise. The user sees the authorization prompt. If the user clicks “Continue”, the service redirects the user back to your site with an auth code: 
https://REDIRECT_URI?code=AUTH_CODE
Your server exchanges the auth code for an access token: 
 POST https://accounts.studentbeans.com/oauth/token?grant_type=authorization_code&code=AUTH_CODE&redirect_uri=REDIRECT_URI&client_id=CLIENT_ID&client_secret=CLIENT_SECRET
The server replies with an access token: 
{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 7200,
  "refresh_token": "REFRESH_TOKEN",
  "created_at": "UNIX_TIMESTAMP"
}
or if there was an error: 
{
  "error": "unsupported_grant_type",
  "error_description": "The authorization grant type is not supported by the authorization server."
}
Security: Note that the service must require apps to pre-register their redirect URIs.

​
User Profiles

In order to retrieve the user’s profile information you can now use the token to authenticate with our API. Me endpoint
GET https://accounts.studentbeans.com/api/v1/me.json?access_token=ACCESS_TOKEN
There are 3 scopes applicable to this endpoint which gives access to certain information: sbid_profile gives access to the following information:
  • Email Address
  • Name
  • Date of Birth
  • Gender
  • Country
  • Avatar image
sbid_education gives access to the following information:
  • University
  • Verification expiry
  • Graduation year
sbid_number gives access to the following information:
  • SBiD Number
The server replies with the user’s information (assuming all scopes are present). Here is a typical response: 
# HTTP Status: 200
{
  "email": "student@example.com",
  "profile": {
    "id": ID,
    "first_name": "FIRST NAME",
    "last_name": "LAST NAME",
    "date_of_birth": "YYYY-MM-DD",
    "gender": "M",
    "country": "UK",
    "avatar": "https://cdn.studentbeans.com/studentbeans/users/profiles/profiles/avatars/XXX/XXX/XXX/thumbnail/avatar.jpg",
    "student_verification": {
      "expires_in": 1469031778,
      "university": "University of Manchester",
      "status": "complete"
    },
    "grad_year": "YYYY",
    "sbid_number": "XXXXXXX"
  }
}

​
Sample Responses

Here are sample responses. These sample responses are both annotated and shortened, to highlight the most useful data and explain what it is. A verified user account. This user account is verified as a student. 
# HTTP Status: 200
{
  "email": "student@example.com",
  "profile": {
    "first_name": "FIRST NAME",
    "last_name": "LAST NAME",
    "date_of_birth": "YYYY-MM-DD",
    "gender": "M",
    "country": "UK",
    "avatar": "https://cdn.studentbeans.com/studentbeans/users/profiles/profiles/avatars/XXX/XXX/XXX/thumbnail/avatar.jpg",
    "student_verification": {
      # When the user account is verified until. Unix time.
      "expires_in": 2602607549,
      # Where the user is a student.
      "university": "University of Manchester",
      # complete = user account completed verification.
      "status": "complete"
    },
    "grad_year": "YYYY",
    # A unique identifier for this user account, scoped to the user account.
    # Remains the same forever, regardless of changes to the verification status.
    "sbid_number": "XXXXXXX"
  }
}
A expired user account. This user account is verified as a student but, that verification has expired. Therefore the profile.student_verification.expires_in key will be in the past. 
# HTTP Status: 200
{
  "email": "student@example.com",
  "profile": {
    "first_name": "FIRST NAME",
    "last_name": "LAST NAME",
    "date_of_birth": "YYYY-MM-DD",
    "gender": "M",
    "country": "UK",
    "avatar": "https://cdn.studentbeans.com/studentbeans/users/profiles/profiles/avatars/XXX/XXX/XXX/thumbnail/avatar.jpg",
    "student_verification": {
      # When the user account expired. Unix time.
      "expires_in": 961612349,
      # Where the user is a student.
      "university": "University of Manchester",
      # complete = user account completed verification.
      "status": "complete"
    },
    "grad_year": "YYYY",
    # A unique identifier for this user account, scoped to the user account.
    # Remains the same forever, regardless of changes to the verification status.
    "sbid_number": "XXXXXXX"
  }
}
A unverified user account, who has started an email verification attempt. This user has started a verification attept by email but, has yet to complete it. The user has not yet clicked on the email in their inbox. 
# HTTP Status: 200
{
  "email": "student@example.com",
  "profile": {
    ...
    "student_verification": {
      # When the user is verified until. Unix time.
      "expires_in": 2602607549,
      # Where the user is a student.
      "university": "University of Manchester",
      # The user account is not verified. Email verification sent, pending action from user.
      "status": "pending_email_verification"
    },
    "grad_year": "YYYY",
    # A unique identifier for this user account, scoped to the user account.
    # Remains the same forever, regardless of changes to the verification status.
    "sbid_number": "XXXXXXX"
  }
}
A unverified user account, with no verification attempts. This user account exists but, has no verification attempts present. This occurs in several situations: a user who has never attempted verification and a user who failed manual verification. 
# HTTP Status: 200
{
  "email": "student@example.com",
  "profile": {
    "first_name": "FIRST NAME",
    "last_name": "LAST NAME",
    "date_of_birth": "YYYY-MM-DD",
    "gender": "M",
    "country": "UK",
    "avatar": "https://cdn.studentbeans.com/studentbeans/users/profiles/profiles/avatars/XXX/XXX/XXX/thumbnail/avatar.jpg",
    "grad_year": "YYYY",
    # A unique identifier for this user account, scoped to the user account.
    # Remains the same forever, regardless of changes to the verification status.
    "sbid_number": "XXXXXXX"
  }
}
An expired access token. 
# Status: 401
{
    "error": "The access token expired"
}
An invalid access token. 
# Status: 401
{
    "error": "The access token is invalid"
}

​
Verification Statuses and Expiry

The response given details the status of a user account’s verification, where the user studies and when that verification will expire. Here is an annotated response. 
# HTTP Status: 200
{
  "profile": {
    ...
    "student_verification": {
      # When the user is verified until. Unix time.
      "expires_in": 1469031778,
      # Where the user is a student
      "university": "UNIVERSITY",
      # The status of the verification.
      # complete = user account completed verification. Either verified or expired.
      # pending_manual_verification = The user account is not verified. Manual verification begun and awaiting approval/rejection from Student Beans
      # pending_email_verification =  The user account is not verified. Email verification sent, waiting for user to click email in inbox.
      "status": "STATUS"
    },
  }
}

If the `profile.student_verification` key is missing entirely, the user account is unverified and has no ongoing verification attempts.