Skip to main content

Validating schoolSecrets

OpenAPI definition

Once you receive a secret you should validate it by attempting to generate a token and checking the resultant token contents.

A Token contains:

  • Estab: The school establishment number
  • Expires: The expiry date of the token
  • Name: Your application name
  • RelyingParty: Your application Id
  • Scopes: An array of the scopes that this school has authorised for your application

You can view the token details by making a request to https://xporter.groupcall.com/api/v1/TokenDetails:

Example call via cURL
curl "https://xporter.groupcall.com/api/v1/TokenDetails" -H "Authorization: Idaas RAELmHpW4eTIiy/Az9JzyW4t...
Example response
{
  "Estab":  "3286198",
  "Expires":  "2018-10-31T09:07:22.2736933Z",
  "Name":  "Example App",
  "RelyingParty":  "live.example.app",
  "Scopes": [
    "AssessmentResults",
    "Attendance",
    "SEN",
    "SENTypes",
    "School",
    "Student",
    "StudentDemographic",
    "StudentExtended",
    "WritebackAttendance"
  ],
  "Message":  null,
  "ExceptionType":  null,
  "ExceptionMessage":  null,
  "InnerException":  null
}

With this content, you can validate that the schoolSecret refresh token is genuine and can securely save it to your platform.

Storing the schoolSecret​

Now you have confirmed the schoolSecret refresh token is from Xporter and know which school it belongs to, you will need to save it into your platform.

We advise that you don’t store the secrets in plain text, to avoid potential compromise or misuse.

tip

If you receive a new schoolSecret refresh token from Xporter, you should invalidate your currently saved session token and generate a new one to ensure you have the latest scopes enabled. You’ll have probably already done this if you have followed the advice to generate the session token on receipt of the schoolSecret refresh token!

Storing the Token​

You should also save the generated session STSToken. We advise that you save the Expiry value alongside session tokens so you can programmatically keep them refreshed.

tip

Xporter does not store session tokens for school/app combinations, we unpack them when a request is made and check the contents of it to determine validity and permissions.