Single Sign-On (SSO)
Single Sign-On (SSO) allows users to authenticate with K12NET through your application, providing a seamless and secure user experience. Here's how you can implement SSO as a Partner:
To integrate Single Sign-On (SSO) into your application, enabling users to log in with their K12NET credentials, follow these straightforward steps:
-
Create a Login Link: Incorporate a link or button within your application labeled "Login with K12NET". This serves as the entry point for users to authenticate via K12NET.
-
Redirect Users for Authentication: When users click the "Login with K12NET" link, redirect them to the K12NET authentication page. Ensure to include your application's
client_idand theredirect_uriin the request. Theredirect_uriis the URL where users should be directed after a successful login. -
Capture the Authorization Code: After the user successfully logs in, K12NET will redirect them back to the
redirect_uriyou specified, appending anauthorization_codeto the query string. Capture thisauthorization_codefrom the user's browser's query string for the next step. -
Verify the User: With the
authorization_codein hand, make a request to the K12NET token endpoint to exchange it for anaccess_token. Then, query the/userinfoendpoint using thisaccess_tokento retrieve the user's information and verify their identity.
By following these steps, you can securely authenticate users with their K12NET credentials, streamlining the login process for your application while maintaining high security standards. This SSO integration ensures a seamless user experience for accessing both K12NET's functionalities and your application's services.
Direct User for Authentication
To initiate the SSO process, direct the user to our authorization endpoint with the necessary query parameters. Here's the URL format you should use:
https://api.k12net.com/GWCore.Web/connect/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=openid profile
Replace YOUR_CLIENT_ID with your client identifier and YOUR_REDIRECT_URI with the URI where you want the user to be redirected after authentication.
Handle the Authorization Code
After the user has logged in, a code will be returned to your application via the redirect URI. This code is used to request an access_token.
Request Access Token
Make a POST request to our token endpoint to exchange the code for an access_token.
curl -X POST https://api.k12net.com/GWCore.Web/connect/token \
-d "grant_type=authorization_code&code=YOUR_AUTHORIZATION_CODE&redirect_uri=YOUR_REDIRECT_URI&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \
-H "Content-Type: application/x-www-form-urlencoded"
Replace placeholders with actual values including the YOUR_AUTHORIZATION_CODE you received after the user's successful login.
Retrieve User Information
Once you have the access_token, you can request the user's information by making a GET request to the userinfo endpoint:
curl -X GET https://api.k12net.com/GWCore.Web/connect/userinfo \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Replace YOUR_ACCESS_TOKEN with the actual access token you obtained.
This will return the user's information, which you can then use within your application according to the permissions granted.
Upon successfully obtaining the access_token and making a GET request to the userinfo endpoint, you will receive a JSON response containing the user's information. Here is the format of the response:
{
"ID": "{b1e15c95-011b-ee11-8137-bc97e1afd933}",
"profile": "Student",
"sub": "54847847844"
}
The ID field contains the unique identifier of the user within K12NET. This identifier is essential for associating the user's data with your application's internal records.
This unique identifier is essential for making subsequent API calls related to the user. It is used to reference the specific user in your application and should be securely stored and handled. Any API requests that require user-specific information will need this ID to retrieve or modify data pertaining to that user in the K12NET system.
The profile field indicates the role of the user within K12NET and can be one of the following values:
-
Student -
Teacher -
Parent -
Staff
This information is critical for determining the user's access level and permissions within your application. Ensure that your application logic handles each user type appropriately to provide a tailored experience.
Remember to handle these requests securely and maintain the confidentiality of all credentials and tokens. The actual implementation may vary depending on the specific setup of your application and should align with best security practices.
To further facilitate the integration of Single Sign-On (SSO) capabilities, we provide a range of additional endpoints that allow Partners to retrieve specific user information. These endpoints are designed to give Partners access to detailed data for students and teachers once SSO authentication is completed. Below are the endpoints and their functionalities:
Acquire Authorization Token: You need to obtain an authorization token to access the K12NET API. This token is used to authenticate your requests and ensure that you have the necessary permissions to access the data. To acquire the authorization token, you need to make a POST request to the token endpoint with your client credentials. Here's an example of how to do this:
curl -X POST https://api.k12net.com/GWCore.Web/connect/token
-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
-H "Content-Type: application/x-www-form-urlencoded"
Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your actual client credentials. The response to this request will include an access_token that you can use to authenticate your subsequent requests. You need to include this token in the Authorization header of your API requests.
Retrieve User Information: Once you have the access token, call the endpoint that matches the user's profile, passing the ID returned by the userinfo endpoint as {user_id}. Every request needs the header Authorization: Bearer YOUR_ACCESS_TOKEN.
Students
Retrieve a student, together with the student's current enrollment:
GET https://api.k12net.com/INTCore.Web/api/Partner/SSO/Students/{user_id}
{
"ID": "365ffb89-8c91-f111-8fbf-98f2b32a1389",
"FullName": "Elif Yılmaz",
"FullNameParts": { "First": "Elif", "Middle": null, "Last": "Yılmaz", "Suffix": null },
"NationalID": "12345678901",
"BirthDate": "2015-04-21T00:00:00",
"Gender": false,
"PhoneNumbers": [ "+90 555 000 00 00" ],
"Emails": [ "[email protected]" ],
"Enrollment": {
"ID": "395ffb89-8c91-f111-8fbf-98f2b32a1389",
"YearID": 2027,
"GradeLevel": "05",
"Track": null,
"LocalId": "512",
"Homeroom": "5/A",
"EntryDate": "2026-08-06T00:00:00",
"School": {
"ID": "64d249ec-4b35-4f30-a316-d045e105f827",
"Name": "Example Middle School",
"LocalId": "2",
"LEA": { "ID": "f740df95-f6ee-df11-815a-002219a888e2", "Name": "Example Schools", "LocalId": "1" }
},
"UsingBus": false
}
}
Retrieve all enrollments of the student in the active school year, for example when the student is enrolled in more than one school:
GET https://api.k12net.com/INTCore.Web/api/Partner/SSO/Students/{user_id}/Enrollments
The response is a list of Enrollment objects with the same fields as above.
Teachers
Retrieve a teacher, together with the teacher's assignments in the active school year:
GET https://api.k12net.com/INTCore.Web/api/Partner/SSO/Teachers/{user_id}
{
"ID": "8d7cfa5c-8c91-f111-8fbf-98f2b32a1389",
"FullName": "Ahmet Demir",
"FullNameParts": { "First": "Ahmet", "Middle": null, "Last": "Demir", "Suffix": null },
"Emails": [ "[email protected]" ],
"CurrentAssignmentID": "907cfa5c-8c91-f111-8fbf-98f2b32a1389",
"Assignments": [
{
"ID": "907cfa5c-8c91-f111-8fbf-98f2b32a1389",
"JobFunctionCode": "1000",
"JobFunctionDescription": "Teacher",
"TeachingAssignmentCode": "1317",
"TeachingAssignmentDescription": "German",
"School": { "ID": "64d249ec-4b35-4f30-a316-d045e105f827", "Name": "Example Middle School", "LocalId": "2" }
}
]
}
CurrentAssignmentID is the assignment (school) the teacher is currently working in on K12NET, when it is one of the listed assignments.
Parents
When the profile is Parent, retrieve the parent and the students the parent is responsible for:
GET https://api.k12net.com/INTCore.Web/api/Partner/SSO/ContactStudents/{user_id}
The response format is described on the Parents page.
Data Returned
The JSON fields returned from these endpoints are controlled by the respective Organization. A field such as BirthDate or NationalID may be available for users in one Organization but not in another; fields that are not shared are returned as null or are left out of the response. Partners must handle the data conditionally and design their applications to gracefully handle the presence or absence of specific fields.
FullNamePartsholds the parts ofFullNameseparately. Empty parts arenull. Depending on how the school records names, all given names may be inFirst.OtherNameandOtherNamePartshold the person's name in English, when the school records one.Genderistruefor male,falsefor female andnullwhen unknown.- An endpoint returns an empty response when the user has no active enrollment or assignment in a school your Partner account can access.
- Responses may also contain the serializer properties
$idand$type; you can ignore them.