OAuth2.0 Authorisation

Please note that this article is for reference for API integrators, not to be used by schools. Schools should use our guidance here.


ScholarPack uses OAuth 2.0 for authorisation.This protocol is widely used for enabling third-party applications to gain access to a limited scope of a resource owner's data over HTTP. Please see RFC-6749 for an overview of the OAuth 2.0 framework.

ScholarPack uses the 'Authorisation Code' grant type for authorisation. This flow allows the user to explicitly authorise a third party (or client) to gain access to their data. 

Once the client has acquired an access token this can be used to make requests on the resource server.

URI Structure

The structure of the URI is as follows:


<subdomain> can be either 'sandbox' or 'services'. Sandbox is the testing environment and services is the production environment.

Authorisation Request

The flow begins with the client redirecting the user to the authorisation URI, using "application/x-www-form-urlencoded" for passing the following parameters: 

Key Description
response_type  This value must be set to 'code'
client_id The client identifier
redirect_uri This is the redirect URI that the user will be redirected to after they have authorised the client.
scope The scope of the access request as a list delimited by a '+' symbol. For instance 'student:read+register:read'
state A value used to maintain state between the request and callback. This should be used to prevent cross-site request forgery (CSRF).

The request must be a GET:

GET /oauth2/authorize/?response_type=code&client_id=testing_api_client&redirect_uri=https://testing-api.com/scholarpack&scope=student:read+staff:read+student-register:read


You will need to have both Admin and System Admin roles on ScholarPackIf you don’t have this, you’ll need to ask your team to give you access by following these instructions: How do I add a user role to a staff member?

login to authorise.png

The school URL must have a trailing slash (/) at the end of the URL in order to login.

The user will be presented with a screen asking for an authorisation decision - along with information about who is making the access request and what scope of data they would like access to.

Screenshot 2024-03-26 at 15.59.39.png


Authorisation Response

Once the user has made a decision the authorisation server will direct the user back to the client redirect URI. If the client is authorised then the response will include 'code' and 'state' as parameters using "application/x-www-form-urlencoded". For example: 

HTTP/1.1 302
Location: https://testing-api.com/scholarpack/?code=bb9G6l43KbbSrydRki7kwL9dm2xJy8D1ivvCB37kEuruRuB2&state=ZEY77VniJIl1hIF1


The authorisation code expires in 10 minutes after generation and can only be used once. 

The length of the authorisation code will be 48 characters.

If the request fails the authorisation server will give the relevant response as outlined in section of RFC-6749.

Access Token Request

Once an authorisation code has been acquired it can be used to exchange for an access token/refresh token. To do so a POST must be made to the token's endpoint with the following parameters: 

Key Description
client_id The client identifier
grant_type This must be set to 'authorization_code'
code This is the code acquired after being authorised by the user.
redirect_uri This must be identical to redirect URI that the user was directed to.

The following is an example of the HTTP request: 

POST /oauth2/token/
Authorization: Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0
Content-Type: application/x-www-form-urlencoded


The Basic Authorisation header is the client id and client secret Base64 encoded in the following format: 'client_id:client_secret'. 

Access Token Response

If the authorisation code is valid then the response will be a JSON object like the following example:

"access_token": "CBJFCFV1wOrs0D14zgLUNkdsCMlqaRNOxMdIWwWBJj",
"expires_in": 864000,
"refresh_token": "1v4EqZPsaW7kqfZR7069XM9XEqIQOVIRx08FGUuXGMp3l6xV",
"scope": "student:read staff:read student-register:read",
"token_type": "Bearer"

The access token can be used to gain access to the requested protected resource.

Making a Request to the API Using the Access Token

Resource Request 

In order to get access to the protected resource a GET request needs to be made for the respective endpoint and the 'access_token' passed as Bearer in the Authorisation header.

GET /api/v1/students/
Authorization: Bearer CBJFCFV1wOrs0D14zgLUNkdsCMlqaRNOxMdIWwWBJj 

The resource server will then return the requested data from the school who authorised the given token. 

Refreshing the Access Token

Refresh Token Request 

Once an access token has expired it can no longer be used to gain access to a protected resource. However refresh tokens can be used to get another access token so that the user doesn't have to again re-authorise the client. To get a refresh and access token a POST request has to be made to the token endpoint with the following parameters:

Key Description
grant_type This value must be set to 'refresh_token'
refresh_token The value of the refresh token being used.
scope The scope of the access request. This is optional, you can use this to reduce the scope of the refreshed token for example. Each scope must be delimited by a space, e.g. 'student:read staff:read'

For example: 

POST /oauth2/token/
Authorization: Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0
Content-Type: application/x-www-form-urlencoded


Refresh Token Response

Upon success the response will be a JSON object with a new access_token and refresh_token. 

"access_token": "EOtPew5fX0Swr6OLxg6vwDcX33G7CO0hhvAEYci9gH",
"expires_in": 864000,
"refresh_token": "kVQnsFOADHPp6355goc84kzebGA55gERwYPAB5B6iUCWBTlw",
"scope": "student:read staff:read",
"token_type": "Bearer"

Revoking a Token 

Revoke Token Request

If you need to revoke a token (for example if it has been compromised) make a request to the revoke endpoint with the following parameters. 

Key Description
token The value of the token.
token_type_hint The type of token, e.g. 'access_token'
client The client_id 

For example: 

POST /oauth2/revoke/
Content-Type: application/x-www-form-urlencoded
Authorization: Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0==

Was this article helpful?
0 out of 0 found this helpful