API Overview

Scholar Snapp Central uses a standard OAuth 2.0 authorization method to control access to its API. OAuth 2.0 is an HTTP-based set of authentication requests and responses, some performed within the browser and some which are performed by server-side code.

The following diagram represents the OAuth 2.0 / API data flow:

The OAuth 2.0 specification can be found at https://tools.ietf.org/html/rfc6749. In particular, the section on the Authorization Code grant flow, section 4.1 (https://tools.ietf.org/html/rfc6749#section-4.1) is useful to understand.

Prerequisites

Scholarship application providers that wish to use the Scholar Snapp Central API must execute a data sharing agreement and register with Scholar Snapp as a client application. Providers may acquire a client registration by emailing contactus@scholarsnapp.org.

There is no charge to connect with Scholar Snapp. The agreement and registration are free.

Once registered, providers receive API credentials (an OAuth Client ID and Client Secret). The Client Secret must be kept secure, it is equivalent to a password. When requesting an application registration, providers must provide a Redirect URI. This will be the URI within the provider application to which Scholar Snapp will return the user when an authorization code is issued.

Details follow.

Data Flow Details

This section provides a step-by-step overview of the Scholar Snapp OAuth 2.0 API handshake for developers. The high-level steps are:

Each step is described in detail, below.

Step 1. Hyperlink to ScholarSnapp.org

The authorization flow is initiated by directing the client’s browser to the Scholar Snapp OAuth 2.0 Authorization endpoint, with a specific set of URL parameters. An example request, and a list of the parameters, are below. Note that you must use secure HTTP (https://) when accessing all Scholar Snapp OAuth 2.0 and API URLs.

Request Base URL: https://auth.scholarsnapp.org/oauth/Authorize 

Parameters:

Example: If you have the following credentials:

• Client ID: client123
• Redirect URI: https://client123.example.org/ScholarSnappConnect
• Optional State String: 81F5063B-917F- 4B29-AFF9-73EA7BA7404D

Then the URL you would provide as a link or redirect the user to would be: 

https://auth.scholarsnapp.org/oauth/Authorize?response_type=code&client_id=client123&redirect_uri=https%3A%2F%2Fclient123.example.org%2FScholarSnappConnect&state=81F5063B-917F-4B29-AFF9-73EA7BA7404D

As noted, the redirect_uri parameter must be URL-encoded and the state parameter is optional.

When the scholarship applicant is directed to this URL (e.g., via a normal link or an HTTP 302 Redirect), the Scholar Snapp API will check to see if the user is logged in to the Scholar Snapp website. If the user is not logged in, they will be prompted to log in.

Step 2. Redirect to the Scholar Snapp Import Landing Page

Once they have logged in to the Scholar Snapp website (or if they were already logged in), they will see a screen similar to the following:

If the user clicks the “Deny” button, they will be sent back to your Redirect URL with a URL parameter named “error” and a value of “access_denied”. However, assuming the user clicks the “Allow” button, the user will be directed to your Redirect URL with the following URL parameters:

Step 3. Retrieve OAuth Token

Now that control has been returned to your application, you can make another request to the Scholar Snapp website to convert the authorization code into an authorization token. This request, unlike the first one, should not be made by the user’s browser, but by a background or server-side request. The method to do so will vary based on the technology your application uses, but a .NET sample is available for review and the process is described below.

The request must be a POST request to the following URL, with the available parameters listed below. The request must include a Basic Authorization HTTP header, constructed by concatenating your client ID, a colon, and your client secret and converting the value to Base64. The body of the request should contain the parameters below, as a URL-encoded form submission.

Request Base URL: https://auth.scholarsnapp.org/oauth/Token

Parameters:

Example: If you have the following credentials:

• Client ID: client123
• Client Secret: abcXYZ
• Redirect URL: https://client123.example.org/ScholarSnappConnect
• The code returned to your Redirect URL in the previous step: 38ecd875531e476a9a41308aed6ce7baefed093d9f7c45049b6a2f31c9b79d07

Then the POST request to Scholar Snapp would look like the one below: 

POST https://auth.scholarsnapp.org/oauth/Token 

Authorization: Basic Y2xpZW50MTIzOmFiY1hZWg==
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=38ecd875531e476a9a41308aed6ce7baefed093d9f7c45049b6a2 f31c9b79d07&redirect_uri=https%3A%2F%2Fclient123.example.org%2FScholarSnappConnect

Note that the Base64 encoding of “client123:abcXYZ” is “Y2xpZW50MTIzOmFiY1hZWg==”

The response will be a JSON string similar to the following:

{
	access_token: "38ecd875531e476a9a41308aed6ce7baefed093d9f7c45049b6a2f31c9b79d07", 
	expires_in: 3600,
	token_type: "bearer"
}

The “token_type” value will always be “bearer” and can be ignored. The “expires in” value is the number of seconds for which the access_token value is valid (in this example, 1 hour). The access_token value itself is the authorization token which can be used to access the Scholar Snapp API (see “API Access” below).

Step 4. Download Scholar Snapp Profile

All methods in the Scholar Snapp API require an authorization token acquired as described in previous sections.

When accessing API methods, it is required that you provide a Bearer Authorization HTTP header, or you will receive a 401 Unauthorized error response. All examples below include such a header.

Retrieve Scholar Snapp Profile

This endpoint will return the Scholar Snapp file of the user who is identified by the provided authorization token. The file is provided as the body of the response and is a standard XML Scholar Snapp file.

Request URL: GET https://auth.scholarsnapp.org/api/profile/snappfile?version=4 

Parameters:

 Example Request: 

• GET https://auth.scholarsnapp.org/api/profile/snappfile?version=4

Authorization: Bearer <authorization_token>

The reply will be a Scholar Snapp Profile as XML.

<?xml version="1.0" encoding="UTF-8"?>
<ScholarshipApplication xmlns="http://www.scholarsnapp.org/scholarshipapplication" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:sds="http://www.scholarsnapp.org/scholarshipapplication" xsi:schemaLocation="http://www.scholarsnapp.org/scholarshipapplication Snapp-Data-Standard-v40.xsd">
	<Context>
		<Created>2018-03-12T20:20:10.001Z</Created>
		<CreatedBy>ScholarSnapp.org</CreatedBy>
		<LastUpdated>2018-03-12T22:20:10.001Z</LastUpdated>
		<LastUpdatedBy>ScholarSnapp.org</LastUpdatedBy>
		<ApplicationLanguage>en-US</ApplicationLanguage>
	</Context>
	<Student>
		<Name>
			<FirstName>Testy</FirstName>
			<LastName>McTestface</LastName>
			<Suffix>Jr.</Suffix>
			<PreferredName>Tron</PreferredName>
		</Name>
		<ContactInfo>
			<Email>testy.mctestface@example.com</Email>
			<PrimaryPhoneNumber>512-555-1212</PrimaryPhoneNumber>
			<IsPrimaryPhoneTextCapable>true</IsPrimaryPhoneTextCapable>
		</ContactInfo>
		<Gender>Male</Gender>
		<Race>White</Race>
		<Ethnicity>NonHispanic</Ethnicity>
		<BirthPlace>
			<City>Santa Monica</City>
			<StateOrProvince>CA</StateOrProvince>
			<Country>US</Country>
		</BirthPlace>
		
		... much more here ...

		</Student>
</ScholarshipApplication>

Step 5. Upload an Updated Scholar Snapp Profile

Your application may choose to offer the applicant the ability to upload their profile to Scholar Snapp. If the applicant does not have a Scholar Snapp account, they will need to complete steps 1 - 3 above, while choosing to register a new account at the end of step 2 (instead of logging in to an existing account). If they do have an existing account, you can use an existing auth_token, or simply repeats steps 1-3 to get a new token. You can then call the profile API endpoint. As above, you must supply the user’s authentication token in a Bearer Authorization HTTP header.

Request URL: https://auth.scholarsnapp.org/api/profile/snappfile?version=4

Parameters:

Example Request:

• POST https://auth.scholarsnapp.org/api/profile/snappfile?version=4 

Authorization: Bearer <authorization_token>
<binary stream of Scholar Snapp data>

If the request is successful, the response will be an HTTP 200 OK response. The body of the response will be a JSON string with the following format:

{
	message: "File successfully transferred. View this information at https://scholarsnapp.org"
}

If the request is not successful because the uploaded data is not a valid Snapp Profile, the response will be an HTTP 400 Bad Request response. The body of the response will be a JSON string with the following format:

{
	message: "The supplied file is not a valid Scholar Snapp (SDS) file.", errorDetails: "<description of all XML validation errors encountered>"
}

If any other error is encountered, the response will be an HTTP 500 Internal Server Error response with no attached error message.