The acronym "API" stands for Application Program Interface and is a term used to describe anything that facilitates interaction with a system or data set. The term API is loosely used to refer to anything from documentation that details how something works to core functions within an existing system, to an entire, separate system which accesses another system or a data set.
While the acronym "API" is used in different contexts to mean different things, in this context, the SSATB’s API is simply a service designed to allow an easy and consistent interface with the existing SSATB’s services – applications, test scores and inquiries. In other words, the SSATB’s API is a web service that lets you programmatically interface with SSATB’s system. As the API user, you will write a program (the client) that makes requests (i.e. API calls) to the SSATB API service and receive a response.
SSATB’s API is a RESTful API, you can think of the basic interaction between an API client (the program you, as the developer, will write) and the SSATB’s API service as very similar to an actual human being browsing the web. The human uses a client program (a web browser like Firefox or Safari) to make requests to a web server ( for instance google.com). The request the web browser makes is specifically formatted to follow HTTP standards, and the response (a web page containing text, images, flash files, etc.) follows the same standard. In this way, you will write a program that sends a specifically formatted request to the SSATB’s API, receives a response, parses it, and then does whatever you may want based on the given response.
Please read through all the material available in this wiki to learn about our API’s. We will post more resources, examples as they become available.
For security reasons, tokens issued by the SSATB token services expire after a set time. The TTL for each token type is:
| Authorization Code: | 5 minutes |
|---|---|
| Access Token: | 1 hour |
| Refresh Token: | 30 days |
Applications that use the API must take the expiration period into account. For example, if the application is developed using the client credentials flow for a system-to-system integration, the application must periodically request new access tokens instead of requesting one at startup and using it for the lifetime of the application.
The expiration time for the access token is also included in the token response under the expires_in field (reported in seconds). Applications are encouraged to dynamically refresh or request new access tokens based on this value instead of hard-coding it to the values in the above table in case the lifetimes change in a future release.
Identity information is captured during the Access Token request and embedded within the token. This allows the APIs to understand who the caller is with just the API token alone.
Depending on which grant type is used, the token either contains generic information about a member school, or a specific user.
POST https://api.ssat.org/oauth/token HTTP/1.1 Content-Type: application/x-www-form-urlencoded grant_type=client_credentials&client_id=[your clientid]&client_secret=[your client secret]&scope=4564
{
"access_token": "1107c268205e753fd007bb4e452446fd",
"expires_in": "3600",
"token_type": "Bearer",
"org_id": "1717",
"issued_at": "1525976812591",
"scope": "1717",
"client_id": "[your clientid]"
}
GET https://api.ssat.org/oauth/authorize?response_type=code&client_id=[your clientid]&redirect_uri=[your redirecturl]&scope=openid%20profile%20offline_access HTTP/1.1
HTTP/1.1 302 Found Location: [your redirecturl]?code=1321caca8e9dcdd209946d3a9dca60b4
POST https://api.ssat.org/oauth/token HTTP/1.1 Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&code=1321caca8e9dcdd209946d3a9dca60b4&client_id=[your clientid]&client_secret=[your clientsecret]&redirect_uri=[your redirecturl]
{
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImEzck1VZ01Gdjl0UGNsTGE2eUYzekFrZnF1RSIsImtpZCI6ImEzck1VZ01Gdjl0UGNsTGE2eUYzekFrZnF1RSJ9.eyJpc3MiOiJodHRwczovL3NzYXRiLWF1dGhvcml6YXRpb24tZGV2LWZlYXR1cmU0LmF6dXJld2Vic2l0ZXMubmV0IiwiYXVkIjoiNldUWXpxVmlpVE14TGF4WGt3cDZBc3E3dHhjWVFpeFEiLCJleHAiOjE1MjU5Nzc1NDIsIm5iZiI6MTUyNTk3NzI0MiwiaWF0IjoxNTI1OTc3MjQyLCJzaWQiOiI3NzMyMGE1MTMxNTM4NzI4ZDYzODYzMmQ3NWYzM2M1NCIsInN1YiI6WyJjMTIwNDIyYS1kMGY3LWUyMTEtYmNkZS0wODAwMjc0MjhkZTEiLCJzc2F0NzYwMEBzc2F0Lm9yZyJdLCJhdXRoX3RpbWUiOjE1MjU5NzcyMzcsImlkcCI6Imlkc3J2Iiwib3JnaWQiOiI3NjAwIiwib3JnbmFtZSI6IlRhZnQgU2Nob29sIiwibmFtZSI6IlNTQVQgU1VQUE9SVCIsImZhbWlseV9uYW1lIjoiU1VQUE9SVCIsImdpdmVuX25hbWUiOiJTU0FUIiwiYW1yIjpbInBhc3N3b3JkIl19.iaWNtYvhMMOkj6OkGxd6pMnetXNpLadIQUGrj5B3nI-ujb7BIE08ICp09voaSiHURGm6l68GEZuJb3XZtK_WYaOXUrJzIjyuBpsPJYTBFYazKLcp9w60cnBYa-t2bgQAMMkRKgNjLDPA1VIwVNTZrWdq-wzyYgB2vwTJRjGMjmrRLHFF-hAg0ZIxlGg4_sLpcHxmCtPjUF9FpmZS2b5Hc6aGExWdnK9DZJgQqNo4GQoH2ylVt3ycKFVOvTTORjAUWrMi-MOhmvCZqaE-I1D9xoelJMsHnJl_1wT70ZdLPNWi5ZB4kLZsM_T0UtrCR81jVME6KrHNRujTCXL3Kt8iqA",
"access_token": "0dc4b19b2fe6dea2ef380348fffdd43f",
"expires_in": "3600",
"token_type": "Bearer",
"refresh_token": "d0d11b0dfa00cb23b86cd426d2b35923",
"claims": "{\"iss\":\"https://ssatb-authorization-dev-feature4.azurewebsites.net\",\"aud\":\"6WTYzqViiTMxLaxXkwp6Asq7txcYQixQ\",\"exp\":1525977542,\"nbf\":1525977242,\"iat\":1525977242,\"sid\":\"77320a5131538728d638632d75f33c54\",\"sub\":[\"c120422a-d0f7-e211-bcde-080027428de1\",\"ssat7600@ssat.org\"],\"auth_time\":1525977237,\"idp\":\"idsrv\",\"orgid\":\"7600\",\"orgname\":\"Taft School\",\"name\":\"SSAT SUPPORT\",\"family_name\":\"SUPPORT\",\"given_name\":\"SSAT\",\"amr\":[\"password\"]}",
"org_id": "7600",
"scope": "openid profile offline_access schoolapp",
"issued_at": "1525977242232",
"client_id": "[your clientid]"
}
POST https://api.ssat.org/oauth/token HTTP/1.1 Content-Type: application/x-www-form-urlencoded grant_type=refresh_token&refresh_token=d0d11b0dfa00cb23b86cd426d2b35923&client_id=[your clientid]&client_secret=[your clientsecret]&redirect_uri=[your redirecturl]
{
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6ImEzck1VZ01Gdjl0UGNsTGE2eUYzekFrZnF1RSIsImtpZCI6ImEzck1VZ01Gdjl0UGNsTGE2eUYzekFrZnF1RSJ9.eyJpc3MiOiJodHRwczovL3NzYXRiLWF1dGhvcml6YXRpb24tZGV2LWZlYXR1cmU0LmF6dXJld2Vic2l0ZXMubmV0IiwiYXVkIjoiNldUWXpxVmlpVE14TGF4WGt3cDZBc3E3dHhjWVFpeFEiLCJleHAiOjE1MjU5ODAwNzcsIm5iZiI6MTUyNTk3OTc3NywiaWF0IjoxNTI1OTc5Nzc3LCJhdF9oYXNoIjoiWXZnVzhGRFNQYW1ScC1CM0pKSEw1QSIsInN1YiI6WyJjMTIwNDIyYS1kMGY3LWUyMTEtYmNkZS0wODAwMjc0MjhkZTEiLCJzc2F0NzYwMEBzc2F0Lm9yZyJdLCJhdXRoX3RpbWUiOjE1MjU5NzcyMzcsImlkcCI6Imlkc3J2Iiwib3JnaWQiOiI3NjAwIiwib3JnbmFtZSI6IlRhZnQgU2Nob29sIiwibmFtZSI6IlNTQVQgU1VQUE9SVCIsImZhbWlseV9uYW1lIjoiU1VQUE9SVCIsImdpdmVuX25hbWUiOiJTU0FUIiwiYW1yIjpbInBhc3N3b3JkIl19.Jyy0G4wSEOeuFSSEA9vtg03nH05hVObGaLc17qf4BgzRwdnb4kCXHRdWki9XCtDdqcqtTdtDhNkBvA7TG0YNgRW_BLJSgm0U1ud_G3nUmwHTTpyKO4VyHIjV7rXwq_4Jgk46KhzN2bsYOjSqk2VYHf9DBM4CDAxvPBiTNbU6jua7z-M1mE1A4bQ_6bR-i2pFSxJMxN-MrTg2iE6-yJH89Jbf-H26ydt_JUHQF6QBZmLMWIk1yYFk4wiIjQJvIQLJ2DFy9WhB-JIzA0Scms5zqG2mFUlNnf2sTVpYacQ7_n_XBchBiu3k4bJYYO-fGlcMS3JFDH8cDYVP8MqwLQKm6Q",
"access_token": "a67529c9897bdf1cad6ba82b47f12bda",
"expires_in": "3600",
"token_type": "Bearer",
"refresh_token": "d0d11b0dfa00cb23b86cd426d2b35923",
"claims": "{\"iss\":\"https://ssatb-authorization-dev-feature4.azurewebsites.net\",\"aud\":\"6WTYzqViiTMxLaxXkwp6Asq7txcYQixQ\",\"exp\":1525980077,\"nbf\":1525979777,\"iat\":1525979777,\"at_hash\":\"YvgW8FDSPamRp-B3JJHL5A\",\"sub\":[\"c120422a-d0f7-e211-bcde-080027428de1\",\"ssat7600@ssat.org\"],\"auth_time\":1525977237,\"idp\":\"idsrv\",\"orgid\":\"7600\",\"orgname\":\"Taft School\",\"name\":\"SSAT SUPPORT\",\"family_name\":\"SUPPORT\",\"given_name\":\"SSAT\",\"amr\":[\"password\"]}",
"org_id": "7600",
"scope": "openid profile offline_access schoolapp",
"issued_at": "1525979777791",
"client_id": "[your clientid]"
}
GET https://api.ssat.org/oauth/endsession?access_token=a67529c9897bdf1cad6ba82b47f12bda&post_logout_redirect_uri=[your post logout redirecturl] HTTP/1.1
HTTP/1.1 302 Post Logout Redirect Location: [your post logout redirecturl]
WHEREAS, SSATB has obtained, through its Student Inquiry, SSAT Score Reporting, and Standard Application Online service, among other means, and owns or has been granted access to admissions and test data and other information regarding secondary school applicants (collectively, “Data”) and provides such Data to its member schools in good standing (“Member Schools”), including certain Member Schools with whom School Service Provider has a contractual relationship (a “Services Agreement”) for the provision of services (the “School(s)”); and
WHEREAS, one or more School(s) has engaged and authorized School Service Provider to process such Data and, subject to the terms and conditions of this Agreement, SSATB, as an additional service to the School(s), has agreed to provide such Data to School Service Provider;
NOW, THEREFORE, in consideration of the foregoing premises and the mutual covenants hereinafter set forth and other valuable consideration (the receipt and adequacy of which each party acknowledges), the parties hereto agree as follows:
1. Grant of Rights. SSATB grants to School Service Provider a limited, non-exclusive, royalty-free, non-transferable, non-sub licensable license during the Term of this Agreement to use the Data for the sole purpose of providing support services to the School(s) as contemplated in the Services Agreements between the School(s) and School Service Provider. School Service Provider shall not acquire ownership of any Data or to any derivative work or any other materials developed, created, or related to the Data; as between the parties, SSATB retains (and School Service Provider hereby assigns to SSATB) any and all rights in and to the foregoing.
2. School Service Provider Obligations.
(a) School Service Provider represents, warrants and covenants that it is authorized by the School(s) to obtain and use the Data on behalf of such School(s); School Service Provider shall provide SSATB in writing a listing of the Schools for which it is so authorized and shall notify SSATB promptly in the event such authority is terminated.
(b) School Service Provider shall use the Data only as expressly permitted in this Agreement and shall not otherwise aggregate, distribute, share, commercialize, or otherwise use the Data.
(c) School Service Provider shall not disclose the Data to anyone other than the School(s) and shall keep the Data in strict confidence in accordance with the terms of this Agreement, its Services Agreements with the School(s), and all applicable laws. The parties acknowledge that School Service Provider utilizes a third party hosting provider and other contractors on its behalf, which parties are subject to contractual obligations of privacy and confidentiality and which parties may have access to Data in connection with the performance of their respective duties. The parties acknowledge and agree that utilizing such parties shall not constitute unauthorized disclosure of Data by School Service Provider under this Agreement.
(d) School Service Provider shall have in place an information security program that has reasonable and appropriate administrative, technical, and physical safeguards to protect the Data (including all personally identifiable information contained therein) from unauthorized access, use and disclosure, in accordance with industry standards for data security, retention, and privacy, which such measures shall include: (a) access controls on information systems, including controls to authenticate and permit access only to authorized individuals; (b) encryption of electronic information including while in transit; (c) reasonable measures to protect against destruction, loss, or damage of the Data due to potential environmental hazards, such as fire and water damage or technological failures; and (d) staff training to implement the information security measures, in accordance with all applicable law and regulation regarding privacy and data security and any applicable data breach notifications laws.
(e) School Service Provider shall maintain procedures to detect and respond to the loss, or unauthorized access, acquisition or use of Data after receipt thereof and while such Data is in School Service Provider’s custody or control (a ”Data Breach”). For clarity, School Service Provider may provide access to the Data to its employees, subcontractors and agents in the course, and for the purpose of, providing the services under the Services Agreement, provided that School Service Provider shall be liable for the acts and omissions of such employees, subcontractors and agents. Further, any loss or unauthorized access, acquisition or use of Data while such Data is in the custody or control of SSATB shall not constitute a “Data Breach” under this Agreement.
(f) School Service Provider shall notify SSATB of (i) a discovered Data Breach within one (1) business day of discovery; and (ii) any Data Breach which School Service Provider considers reasonably likely to have occurred within three (3) business days of discovery. Each party shall fully cooperate with the other party in remedying and addressing such Data Breach. School Service Provider shall undertake actions required by applicable law and regulation related to notifications to affected persons or entities resulting from any Data Breach. School Service Provider shall promptly make available to SSATB appropriate details of the Data Breach and shall use commercially reasonable efforts to investigate and prevent the recurrence of such Data Breach.
(g) School Service Provider has obtained and will maintain during the Term errors and omissions insurance coverage with an aggregate limit in the amount of at least $2 million, including security and privacy coverage and cyber extortion coverage, each with liability limits of at least $2 million.
(h) School Service Provider will indemnify, defend, and hold harmless SSATB, including its officers, directors, and employees against any and all third party claims, penalties, damages, costs, judgments, reasonable attorneys’ fees and any other expenses relating to such claims arising out of or resulting from (i) School Service Provider’s unauthorized use of the Data and (ii) from any Data Breach caused by School Service Provider’s breach of its obligations under Section 2d and/ or 2e of this Agreement.
3. SSATB Obligations.
(a) SSATB acknowledges and agrees that the Data will be provided by SSATB to School Service Provider by means of a software interface utilizing an application program interface (“API”). SSATB will provide (and regularly update) all information reasonably necessary, including without limitation API access to Data, to enable School Service Provider to develop, provide and maintain such interface for each School. SSATB will also provide such additional information as reasonably requested by School Service Provider in order for School Service Provider to comply with the terms of this Agreement, including without limitation information necessary to verify whether a School is a Member School.
4. Term/ Termination of Agreement.
(a) The term of this Agreement (“Term”) shall commence as of the Effective Date and shall continue until June 30, 2017 (the “Initial Term”), unless otherwise terminated by either party as set forth herein. Thereafter, this Agreement shall automatically renew for successive terms of two (2) years unless either party provides the other at least one hundred and eighty (180) days’ advance written notice of its intent not to renew (the Initial Term and all renewal terms hereunder collectively, the “Term”).
(b) In the event either party defaults in any obligation in this Agreement, the non-defaulting party shall give written notice of such default. If the party in default has not cured the default within thirty (30) days of receipt of the notice, the non-defaulting party may terminate this Agreement by delivering written notice thereof to the defaulting party.
(c) SSATB may terminate this Agreement upon at least one hundred and eighty (180) days’ advance written notice in the event that SSATB changes its Data license model for all licensees, provided however that SSATB will offer School Service Provider the opportunity to enter into an amendment to this Agreement or a new Data License Agreement effective upon termination of this Agreement containing terms and conditions no less favorable than those provided to other third parties reflecting the new Data license model implemented by SSATB.
(d) The license rights under this Agreement will terminate automatically with respect to a particular School if (i) School Service Provider is no longer authorized by such School(s) to receive Data or provide services with respect to the Data applicable to such School; and/or (ii) the agreement between a School and SSATB terminates and such School is no longer a Member School having a right to receive such Data.
(e) Upon termination of this Agreement, the license set forth in Section 1 shall immediately and automatically terminate and School Service Provider shall promptly delete all Data in its possession. The terms and provisions of this Agreement that by their sense and context are intended to survive the performance thereof by the parties shall survive termination of this Agreement.
5. Audit. During the Term of this Agreement and for a period of two (2) years thereafter: (a) School Service Provider shall maintain reasonably complete and accurate records relating to performance of its obligations under this Agreement, including without limitation use of the Data provided hereunder, and (b) SSATB or its authorized representatives may audit such records maintained by School Service Provider during School Service Provider’s regular business hours upon at least fifteen (15) business days’ prior written notice. Such audits shall be solely for the purpose of verifying School Service Provider’s performance of its obligations under this Agreement and/or to enable SSATB to comply with all applicable law and regulation. In conducting any such audit, SSATB shall use reasonable efforts to minimize disruption to School Service Provider’s business operations. In each twelve (12) month period, SSATB shall be entitled to conduct one (1) such audit. Each audit shall be at the sole expense of SSATB, provided that School Service Provider shall bear its own expenses related to responding to reasonable requests for information from SSATB in the course of the audit.
6. No Warranty; Limitation of Liability. SCHOOL SERVICE PROVIDER ASSUMES TOTAL RESPONSIBILITY FOR ITS USE OF THE DATA. THE DATA IS PROVIDED “AS IS” WITHOUT ANY WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, EITHER IN FACT OR BY OPERATION OF LAW, STATUTORY OR OTHERWISE, AND SSATB DISCLAIMS ANY AND ALL WARRANTIES OF MERCHANTABILITY, DATA ACCURACY, OR FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL SSATB BE LIABLE TO SCHOOL SERVICE PROVIDER FOR UNAVAILABILITY OF, OR SCHOOL SERVICE PROVIDER’S DELAY IN RECEIVING, THE DATA. EXCEPT FOR THE PARTIES’ OBLIGATIONS UNDER SECTIONS 2(d), 2(e) AND 2(h), NEITHER PARTY SHALL BE LIABLE TO FOR SPECIAL, INCIDENTAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES OF ANY NATURE ARISING UNDER THIS AGREEMENT, FOR ANY REASON, INCLUDING WITHOUT LIMITATION, THE BREACH OF THIS AGREEMENT, WHETHER SUCH LIABILITY IS ASSERTED ON THE BASIS OF CONTRACT, TORT (INCLUDING NEGLIGENCE OR STRICT LIABILITY), OR OTHERWISE, EVEN IF A PARTY HAS BEEN WARNED OF THE POSSIBILITY OF SUCH DAMAGES.
7. Miscellaneous. This Agreement constitutes the entire and integrated agreement between the parties hereto and shall not be modified, amended, or changed in any way except by a written agreement signed by the parties hereto. This Agreement does not and shall not be deemed to constitute a partnership or joint venture between the parties and neither party nor any of their respective directors, officers, employees or agents shall, by virtue of the performance of their obligations under this Agreement, be deemed to be an agent or employee of the other. School Service Provider shall not delegate, assign, sublicense or transfer any rights or obligations under this Agreement without the prior written approval of SSATB. This Agreement shall be governed by and interpreted according to the laws of the State of New Jersey. If any part of any provision of this Agreement shall be invalid or unenforceable under applicable law, such part shall be ineffective to the extent of such invalidity only, without in any way affecting the remaining parts of such provision or the remaining provisions of this Agreement. This Agreement may be executed in separate counterparts, each of which shall be deemed an original document and both of which together will constitute one and the same instrument.