Processing Secrets

Processing Successful Data Authorisations

When a school successfully processes their invitation to share data with your application, we will send you a schoolSecret.

Your application must receive it and store it securely. It will be used to generate a token for the given school to access the Xporter API.

To receive the schoolSecret, your application must be able to receive a callback payload from Xporter.

At the end of the authorisation process we will make a server-side POST to the API endpoint that you have specified in your Xporter app configuration settings.

The POST will contain the following URL encoded body content similar to this example:

schoolSecret=0755658d-0c81-4bfc-93a2-77b9e873914f&schoolId=3286198&schoolEmail=rrainey%40groupcall.com
&schoolName=Testing+School&templateScopes=AssessmentResults%2CAttendance%2CSchool%2CSEN%2CSENTypes%2CStudent%2CStudentDemographic%2CStudentExtended%2CStudentReligion%2CWritebackAttendance
&scopes=AssessmentResults%2CAttendance%2CSchool%2CSEN%2CSENTypes%2CStudent%2CStudentDemographic%2CStudentExtended%2CStudentReligion%2CWritebackAttendance
&thirdParty=XporterOnDemand&partnerId=live.example.app

Configuring your authorisation endpoint

You can configure your URL endpoint that will receive the POST via your application settings in the Xporter Portal

Authorisation Confirmation Properties

Property	Example Value	Description
schoolSecret	0755658d-0c81-4bfc-93a2-77b9e873914f	Per school refresh token used to generate API request signing token via the STS
schoolId	3286198	School’s establishment number. You should ensure each school in your platform has the correct value assigned. Used when generating token via the STS
schoolEmail	[email protected]	Email address of the main contact for the school
schoolName	Testing+School	The school’s name
templateScopes	AssessmentResults, Attendance, School, SEN, SENTypes, Student, StudentDemographic, StudentExtended, StudentReligion, WritebackAttendance	The full list of scopes that this application is configured with
Scopes	AssessmentResults, Attendance, School, SEN, SENTypes, Student, StudentDemographic, StudentExtended, StudentReligion	The specific scopes that have been authorised for this application / school pair
thirdParty	XporterOnDemand	Marker to identify this as an authorisation for Xporter on Demand
partnerId	live.example.app	The ID of the partner application for whom this authorisation was generated. Also used when generating token via the STS
authorisationPaused	true	Optional additional parameter that indicates a school has opted to pause the data flow while they make changes to the selection of individuals included

Example: A very simple PHP function that reads GET and POST parameters:

PHP Example that can receive an authorisation payload

function getParameter($paramName)
{
                if (!array_key_exists($paramName, $_REQUEST))
                                return "";
                return $_REQUEST[$paramName];          
}

$schoolId = getParameter("schoolId");
$schoolName = getParameter("schoolName");
$schoolEmail = getParameter("schoolEmail");
$schoolSecret = getParameter("schoolSecret");
$templateScopes = getParameter("templateScopes");

$consentok = ($schoolSecret != "");

C# Example that can receive an authorisation payload

[HttpPost]
public IActionResult ProcessPOSTBody(string schoolSecret, string schoolId, string schoolEmail, string schoolName, string templateScopes, string scopes, string thirdParty, string partnerId)
{
    // Process the POST body parameters as needed
    string secret = schoolSecret;
    string schoolId = schoolId;
    string schoolEmail = schoolEmail;
    string schoolName = schoolName;
    var scopesList = scopes.Split(',');
    string thirdPartyName = thirdParty;
    string partnerId = partnerId;

    // Validate the schoolSecret property
    if (!ValidateSecret(schoolSecret))
    {
        return BadRequest("Invalid schoolSecret");
    }

    // Return a response to the client
    return Ok();
}

private bool ValidateSecret(string secret)
{
    // Implement secret validation logic here...
}

Next step - Validation