School API Tokens

OpenAPI definition

The Xporter REST API supports token authorisation using a custom bearer style Authorization header.

Example authorization header

Authorization: Idaas {STSToken}

Generating a School API Token

To generate a token, a POST is made to the Xporter STS and an object is returned containing the token

POST Object Fields

Field	Type	Example	Description
estab	String	3281102	School establishment number you are generating a token for
relyingParty	String	app.example.dev	Your application Id
password	String	b9aef7a6-3ee4-4935-98ff-6afe46447213	Your application management or school secret
thirdpartyid	String	XporterOnDemand	The service for which you are authenticating (Always "XporterOnDemand")

Include the estab property and pass the schoolSecret that you will have received following authorisation by a school.

curl --request POST \
     --url https://xporter.groupcall.com/api/oauth/GetToken  \
     --header 'Content-Type: application/json'
     --data '
        { 
            "estab":"{schoolId}", 
            "relyingParty":"{applicationId}", 
            "password":"{schoolSecret}", 
            "thirdpartyid":"XporterOnDemand" 
        }
      '

Important

You will need to generate and use a token per school to access the school data APIs

Token Responses

Example Successful Response

{
  "token": "JhS0X....esMbPoHUOY=",
  "expires": "2021-04-17T09:34:46.402555Z",
  "Message": null,
  "ExceptionType": null,
  "ExceptionMessage": null,
  "InnerException": null
}

You will want to save/store the token with its expiry value so you can refresh the token ahead of time.

Example Failed Response

{
  "token":  null,
  "expires":  "0001-01-01T00:00:00",
  "Message":  null,
  "ExceptionType":  null,
  "ExceptionMessage":  "Relying Party not found for estab or secret not correct",
  "InnerException":  null
}

Example AuthorisationPaused Response

{
    "token":  null,
    "expires":  "0001-01-01T00:00:00",
    "Message":  null,
    "ExceptionType":  null,
    "ExceptionMessage":  "Authorisation is currently paused while the school finalises the selection of people they wish to include in this feed.",
    "InnerException":  null
}

GDPR Functionality

You will receive an Authorisation Paused response when attempting to generate a token if the school opts to make amendments to which people are included in the data feed during initial authorisation.