Please note that this article is for reference for API integrators, not to be used by schools. Schools should use our guidance here.
Authorisation
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:
https://<subdomain>.scholarpack.co.uk/oauth2/<endpoint>/
<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 ScholarPack. If 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?
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.
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 4.1.2.1 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
grant_type=authorization_code&code=bb9G6l43KbbSrydRki7kwL9dm2xJy8D1ivvCB37kEuruRuB2&redirect_uri=https://testing-api.com/scholarpack
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
grant_type=refresh_token&refresh_token=1v4EqZPsaW7kqfZR7069XM9XEqIQOVIRx08FGUuXGMp3l6xV&scope=student%3Aread%20staff%3Aread
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==
token=xtQRZJ82pbkRc5Xe3jJwfE6n8m0NaSJKoadYbBJrqy&token_type_hint=access_token&client=testing_api_client