API Overview

Scholar Snapp Central uses a standard OAuth2 authorization method to control access to its API. OAuth2 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 OAuth2 / API data flow:

The OAuth2 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) will be beneficial.

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 known client application. Providers may acquire a client registration by emailing contactus@scholarsnapp.org.

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 URL. This will be the URL 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 OAuth2 / 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 OAuth2 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 OAuth2 and API URLs.

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

Parameters:

Example: If your client ID is “client123”, your registered Redirect URL is “https://client123.example.org/ScholarSnappConnect”, and your unique state string is “81F5063B-917F- 4B29-AFF9-73EA7BA7404D”, then the URL you would 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

When the scholarship applicant is directed to this URL (e.g., via a normal link or an HTTP 302 Redirect), the Scholar Snapp website will check to see if the user is logged in to the Scholar Snapp website. If they are not, 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 redirected 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 your client ID is “client123”, your client secret is “abcXYZ”, your registered Redirect URL is “https://client123.example.org/ScholarSnappConnect”, and the code returned to your redirect URL is “38ecd875531e476a9a41308aed6ce7baefed093d9f7c45049b6a2f31c9b79d07”, then the POST request to Scholar Snapp would look like the one below. Note that the Base64 encoding of “client123:abcXYZ” is “Y2xpZW50MTIzOmFiY1hZWg==”

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

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.

API URL:

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

Parameters:

• version. The version of the Snapp XML being requested. Valid values are 2 and 3. All new implementations for the 2017-2018 application cycle should develop for and request version 3 (as shown in the URL above). Omitting the version parameter will return Scholar Snapp v2.0 XML.

Example Request: 

• GET https://auth.scholarsnapp.org/api/profile/snappfile?version=3 Authorization: Bearer <authorization_token>

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 they do 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 the 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.

API URL:

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

Parameters:

• version. The version of the Snapp XML being sent. Valid values are 2 and 3. All new implementations for the 2017-2018 application cycle should develop for and request version 3 (as shown in the URL above). Omitting the version parameter will tell Snapp Central to expect Scholar Snapp v2.0 XML.
• The body of the HTTP request should be the binary stream of the Scholar Snapp XML file.

Example Request:

• POST https://auth.scholarsnapp.org/api/profile/snappfile?version=3 
  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 SDS file, 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.

When calling this method, it is important to note (and to inform the user) that this does not directly update their profile. Instead, this method will create a new potential revision of their profile; they can visit their profile at https://www.scholarsnapp.org/ to view pending changes to their profile and individually approve or exclude them from their updated profile.