.svg)
This article provides an overview of the Data API schema OAuth 2 authorization.
In this article
OAuth 2 authorization - “Client credentials” grant
Data API schema
Data API schema reflected in SSO Passport API data schema document.
OAuth 2 Authorization
Request:
The request for client credentials must contain WWW BASIC authorization with both the client_id and client secret key in the request header, such as: ‘Authorization’: ‘Basic {data}’, where data = Base64.encode(‘{client_id}:{client secret}’).
|
POST |
datahub/oauth/token |
Endpoint for authenticating a client. |
| Parameter | Mode | Type | Description |
| grant_type | required | String | The type of the response (should be: ‘client_credentials’) |
Example:
| Method | POST |
| URL | https://{hostname}/datahub/oauth/token |
| Body | grant_type=client_credentials |
| Headers | Authorization: Basic Y2xpZW50aWQ6Y2xpZW50c2VjcmV0 |
Response:
The API returns the following response on successful authentication:
{
"access_token": "zyx",
"token_type": "bearer",
"expires_in": 7199
}
| Field | Type | Description |
| access_token | String | OAuth 2.0 Access Token |
| token_type | String | Token type, which is always 'bearer.’ |
| expires_in | Integer | Expiration time in seconds |
| scope | String | Expiration time in seconds |
API Overview
Districts
|
GET |
/v1/districts |
Retrieves a list of districts you have access to |
|
GET |
/v1/districts/{id} |
Retrieves information of a specific district |
|
GET |
/v1/districts/{id}/schools |
Retrieves a list of schools you have access to for a specific district |
|
GET |
/v1/districts/{id}/teachers |
Retrieves a list of teachers you have access to for a specific district |
|
GET |
/v1/districts/{id}/students |
Retrieves a list of students you have access to for a specific district |
|
GET |
/v1/districts/{id}/sections |
Retrieves a list of sections you have access to for a specific district |
|
GET |
/v1/districts/{id}/groups |
Retrieves a list of groups you have access to for a specific district. These can be LDAP or Google groups. Manually created groups in Passport will not be listed here |
|
GET |
/v1/districts/{id}/admins |
Retrieves all the users with admin access to a district |
|
GET |
/v1/districts/{id}/status |
Retrieves the status of a district |
|
GET |
/v1/districts/{id}/events |
Retrieves all events for all resources belonging to this district |
|
GET |
/v1/districts/{id}/contacts |
Retrieves all contacts of all students belonging to this district |
Teachers
|
GET |
/v1/teachers |
Gets a list of teachers you have access to |
|
GET |
/v1/teachers/{id} |
Get only a specific teacher's information |
|
GET |
/v1/teachers/{id}/events |
Retrieves events for teachers |
|
GET |
/v1/teachers/{id}/sections |
Retrieves a list of all sections for a teacher |
|
GET |
/v1/teachers/{id}/school |
Retrieves information about the school for a teacher |
|
GET |
/v1/teachers/{id}/district |
Retrieves district information for a teacher |
|
GET |
/v1/teachers/{id}/students |
Retrieves all students that a teacher has in their sections |
|
GET |
/v1/teachers/{id}/grade_levels |
Retrieves a list of all grade levels taught by a specific teacher |
Students
|
GET |
/v1/students |
Gets a list of students you have access to |
|
GET |
/v1/students/{id} |
Get only a specific student's information |
|
GET |
/v1/students/{id}/events |
Retrieves events for students |
|
GET |
/v1/students/{id}/sections |
Retrieves a list of all sections for a student |
|
GET |
/v1/students/{id}/school |
Retrieves information about the school for a student |
|
GET |
/v1/students/{id}/district |
Retrieves district information for a student |
|
GET |
/v1/students/{id}/teachers |
Retrieves all teachers for a student |
|
GET |
/v1/students/{id}/contacts |
Retrieves all contacts for a student |
Sections
|
GET |
/v1/sections |
Gets a list of sections you have access to |
|
GET |
/v1/sections/{id} |
Get only a specific section's information |
|
GET |
/v1/sections/{id}/events |
Retrieves events for sections |
|
GET |
/v1/sections/{id}/school |
Retrieves information about the school for a section |
|
GET |
/v1/sections/{id}/district |
Retrieves district information for a section |
|
GET |
/v1/sections/{id}/students |
Retrieves a list of all the section's students |
|
GET |
/v1/sections/{id}/teachers |
Retrieves a list of all the section's teachers |
|
GET |
/v1/sections/{id}/teacher |
Retrieves information about the primary teacher of a section |
Schools
|
GET |
/v1/schools |
Gets a list of schools you have access to |
|
GET |
/v1/schools/{id} |
Get only a specific school's information |
|
GET |
/v1/schools/{id}/events |
Retrieves events for schools |
|
GET |
/v1/schools/{id}/teachers |
Retrieves a list of all teachers for a specific school |
|
GET |
/v1/schools/{id}/students |
Retrieves a list of all students for a specific school |
|
GET |
/v1/schools/{id}/sections |
Retrieves a list of all sections for a specific school |
|
GET |
/v1/schools/{id}/groups |
Retrieves a list of groups you have access to for a specific school. These can be LDAP or Google groups. Manually created groups in Passport will not be listed here |
|
GET |
/v1/schools/{id}/district |
Retrieves district information for a school |
|
GET |
/v1/schools/{id}/contacts |
Retrieves all contacts of all students belonging to this school |
Groups
|
GET |
/v1/groups |
Retrieves a list of groups you have access to. These can be LDAP or Google groups. Manually created groups in Passport will not be listed here |
|
GET |
/v1/groups/{id} |
Get only a specific group's information |
|
GET |
/v1/schools/{id}/members |
Retrieves a list of members belonging to this group. Can be teachers, students, etc. |
District_admins
|
GET |
/v1/district_admins |
Retrieves all users with admin access to a district |
|
GET |
/v1/district_admins/{id} |
Retrieves a district admin |
School_admins
|
GET |
/v1/school_admins |
Gets a list of school admins you have access to |
|
GET |
/v1/school_admins/{id} |
Get only a specific school admin's information |
|
GET |
/v1/school_admins/{id}/schools |
Retrieves all schools for a school admin |
Contacts
|
GET |
/v1/contacts |
Gets a list of student contacts you have access to |
|
GET |
/v1/contacts/{id} |
Get only a specific student contact's information |
|
GET |
/v1/contacts/{id}/student |
Retrieves the student for a contact |
|
GET |
/v1/contacts/{id}/district |
Retrieves the district for a contact |
Events
|
GET |
/v1/events |
Gets a list of all events that have occurred within data you have access to see |
|
GET |
/v1/events/{id} |
Retrieves specific event information |
Caution:
Navigation using "page" parameter is not supported in combination with starting_after or created_since. Use "rel": "NEXT" in “links” section of JSON API response.
Supported event types
|
Created |
Updated |
Deleted |
|
schools.created students.created studentcontacts.created teachers.created sections.created schooladmins.created groups.created |
schools.updated students.updated studentcontacts.updated teachers.updated sections.updated schooladmins.updated groups.updated |
schooladmins.deleted sections.deleted teachers.deleted studentcontacts.deleted students.deleted schools.deleted groups.deleted |
|
Access Granted |
Access Revoked |
|
schools.access_granted students.access_granted studentcontacts.access_granted teachers.access_granted sections.access_granted schooladmins.access_granted groups.access_granted |
schools.access_revoked students.access_revoked studentcontacts.access_revoked teachers.access_revoked sections.access_revoked schooladmins.access_revoked groups.access_revoked |
Typical request parameters
|
Parameter |
Mode |
Type |
Description |
|
access_token |
Required |
String |
The access token obtained during authorization |
|
id |
Required |
GUID |
An ID of a requested entity |
|
limit |
Optional |
Number |
Max records returned (default 100) |
|
created_since |
Optional |
ISO 8601 |
Applies to /events API. Example: created_since=2016-07-26T16:35:04.084Z Support for “since” query parameter is being deprecated. GG4L encourages use of “starting_after” parameter instead. |
|
starting_after |
Optional |
Number |
{miliseconds_from_epoch} Example=1548944937314 |
|
ending_before |
Optional |
Number |
{miliseconds_from_epoch} Example=1548944937314 |
|
page |
Optional |
Number |
Which page of results to return (default 1) Navigation using the "page" parameter is not supported in combination with starting_after or created_since. Use "rel": "NEXT" in the “links” section of JSON API response. |
|
access_events |
Optional |
Boolean |
This parameter is applicable only to /events API If it set (access_events=true) - API will be returning ALL types of events, including Access Events. |
An example of an Access Event:
With a single data entity:
{
"data": {
"id": "5457f15e-2023-43c1-8d07-bbf788a0f84c",// GUID of the Event itself
"type": "students.access_granted",// Event type
"data": {
"object": {
"id": "0a909db2-5180-4601-9908-bfd14c0a9eb9"// GUID of the object
}
},
"created": "2020-08-12T10:46:02.730Z"// Time
},
"uri": "/v1/events/5457f15e-2023-43c1-8d07-bbf788a0f84c"// Endpoint to get this event by guid
}
Structure of JSON response from API
With a single data entity:
{
"data": {
"id": "000bc9f5-8496-4b40-92d5-97d74f9b21f8",
"attribute1": "value of attribute 1",
"attribute2": "value of attribute 2",
"attribute3": "value of attribute 3"
},
"links": [
{
"rel": "self",
"uri": "/v1/entityname/000bc9f5-8490-4b4c-92d5-97d74f9b21f8"
},
{
"rel": "related-entity1",
"uri": "/v1/entityname/000bc9f5-8490-4b4c-92d5-97d74f9b21f8/related-entity1"
},
{
"rel": "related-entity2",
"uri": "/v1/districts/000bc9f5-8496-4b40-92d5-97d74f9b21f8/related-entity2"
}
]
}
With multiple data entities:
{
"data": [
{
"data": {
"id": "000bc9f5-8496-4b40-92d5-97d74f9b21f8",
"attribute1": "value of attribute 1",
"attribute2": "value of attribute 2",
"attribute3": "value of attribute 3"
},
"uri": "/v1/entityname/000bc9f5-8496-4b4c-92d5-97d74f9b21f8"
},
{
"data": {
"id": "111ac1f5-8496-4b40-92d5-97d74f9b21f9",
"attribute1": "value of attribute 1",
"attribute2": "value of attribute 2",
"attribute3": "value of attribute 3"
},
"uri": "/v1/entityname/111ac1f5-8490-4b4c-92d5-97d74f9b21f9"
},
...
],
"links": [
{
"rel": "NEXT",
"uri": /v1/entityname?search_token=2.2.148.FORWARD.111ac1f5-8490-4b4c-92d5-97d74f9b21f9"
},
{
"rel": "SELF",
"uri": "/v1/entityname"
}
]
}
Pagination
Every response contains element links that contains URLs to retrieve related data.
|
rel |
Description |
|
SELF |
URI that was sent for this request |
|
PREV |
URI that can be used to retrieve previous bunch of data |
|
NEXT |
URI that can be used to retrieve next bunch of data |