The Scholar Snapp website 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 API must register with Scholar Snapp as a known client application. You may acquire a client registration by emailing contactus@scholarsnapp.org. Once you have registered, you will receive a Client ID and Client Secret. Store the Client Secret in a safe place; it is equivalent to a password. When requesting an application registration, you must provide a Redirect URL. This will be the URL within your application to which Scholar Snapp will return the user when an authorization code is issued (see below for more details).
Data Flow Details
The following sections provide additional detail on each step of the Scholar Snapp OAuth2 / API handshake.
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://www.scholarsnapp.org/OAuth/Authorize Parameters:
Parameter Name | Required? | Value |
|---|---|---|
response_type | Yes | “code” (string literal, always the same) |
client_id | Yes | The Client ID assigned to you by Scholar Snapp |
redirect_uri | Yes | The URL you wish the authorization code to be returned to when the user grants your access request. This value must exactly match the value you provided in your Scholar Snapp registration. It is recommended this be a secure HTTP (https://) URL. Note that this value must be URL encoded. |
state | No | This value will be returned to your application (at the Redirect URL provided above) exactly as passed. It is recommended to provide a unique value for this parameter in order to prevent replay attacks. |
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://www.scholarsnapp.org/OAuth/Authorize?response_type=code&client_id=client123&redirect_u ri=https%3A%2F%2Fclient123.example.org%2FScholarSnappConnect&state=81F5063B-917F-4B29- AFF9-73EA7BA7404D
When the scholarship applicant is directed to this URL (via a normal link or a 302 Redirect, for example), 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 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 access” button, the user will be directed to your Redirect URL with the following URL parameters: