Authorisation

To access profile information, you need an access token. Access tokens are bound to a user, and the user first needs to authorise your app. We use the OAuth 2 protocol to manage that authorisation between you, the user and us.

OAuth 2 provides several "grant types" for different use cases. We currently support the "Authorization Code" grant type, intended for apps running on a web server.

If you are not configuring an OAuth 2 library or client, skip to the next section to implement the authorisation step manually.

Configuring an auth client or library

Auth libraries and clients that support the OAuth 2 flow can be configured to manage this authorisation for you. Here, you'll find some notes on how to configure your preferred tooling to work with our authorisation service.

Table of common options

These may not exactly match your preferred tooling but they're listed as a guide to help you get set up.

Grant type	Authorisation code.
Authorisation URL	https://www.studentbeans.com/sso/[consumer supergroup] - you can see which values you can use for consumer supergroup in the API Reference.
Access Token URL	https://accounts.studentbeans.com/oauth/token
Refresh Token URL	https://accounts.studentbeans.com/oauth/token
Auth scheme	Authorization request header with Bearer prefix (recommended), request body or request URL.
Client ID	The client ID you were given when you registered with us.
Client secret	The client secret you were given when you registered with us.
Callback URL (or Redirect URI)	Two names for the same thing. This must be a redirect URI that you have registered with us.
Scope(s)	Not used.
State	Not used.

Country

In addition to the above, you must ensure that your tooling is configured to include the country parameter in the authorisation URL. This should be set to uk if your client country is the UK, and an ISO 3166 two-letter country code otherwise.

Example:

country=uk

Tracking in the Redirect URI

You can include additional query parameters on your redirect URI, which may be useful for passing information or tracking users on their round-trip to our authorisation service. These redirect URIs are identical to us:

https://example.com/oauth/callback
https://example.com/oauth/callback?campaign=XYZ
https://example.com/oauth/callback?utm_source=xyz&utm_medium=social&utm_campaign=abc&utm_term=search+for+your+website

And will all work, as long as you have registered the part before the ? with us. When we redirect users back to your app, we will include any query parameters that you added.

Please note:

• You must encode the entire redirect URI as a URI component
• You cannot use a parameter called code because it will be overwritten with the authorisation grant code.

Support

We are not able to offer technical support for any OAuth 2 client or library and the above is just a guide - it may not exactly match what your preferred tooling offers.

If you need to customise the flow beyond what your tooling supports, head to the next section to find out how to implement the authorisation step manually.

Manual authorisation flow

Log a user in

Create a "Log In" link, sending the user to:

https://www.studentbeans.com/sso/[consumer supergroup]?response_type=code&client_id=[...]&redirect_uri=[...]&country=[...]

Note the domain: www.studentbeans.com. These parameters are all required. Descriptions of query parameters and the possible values for the consumer supergroup can be found in the API reference.

When the user authorises your app

When your user has successfully logged in, verified (if necessary) and authorised your app, they will be redirected in their browser to your redirect URI, with the code query parameter containing an authorisation grant code.

https://[redirect URI]?code=[auth code]

This authorisation grant code (auth code) is used in conjunction with your client ID and secret to obtain an access token, and cannot be used by itself to access our API. It is valid for two hours.

note

If you include any additional query parameters in the redirect_uri in your login link, they will be added to this URI. If you include one called code, it will be overwritten.

Get an access token

Once you have the authorisation grant code, you can make an HTTP POST request to our API to exchange it for an API access token. This access token is what gives you access to the user's verification information.

Request

POST https://accounts.studentbeans.com/oauth/token?grant_type=authorization_code&code=[...]&redirect_uri=[...]&client_id=[...]&client_secret=[...]

Note the domain: accounts.studentbeans.com. These parameters are all required. Descriptions can be found in the API reference.

warning

Because we require your client secret here, this request must be made from your server, not from client-side JavaScript or a mobile app.

Response

Success

{
  "access_token": "[...]",
  "token_type": "Bearer",
  "expires_in": 2419199,
  "refresh_token": "[...]",
  "created_at": "[a unix timestamp]"
}

Error example

{
  "error": "unsupported_grant_type",
  "error_description": "The authorization grant type is not supported by the authorization server."
}

Now that you have an access token, you can head to the next step and access your user's verification information. Each access token is scoped to an individual user, so you need to repeat this for each user you want to verify.