Authentication
Authentication in the context of an Ed-Fi ODS / API is essentially the process of credential exchange and verification to establish that a client is allowed to access the platform. Authentication in an Ed-Fi ODS / API is handled using two-legged OAuth 2.
Before accessing the resources in an Ed-Fi ODS / API platform, client applications need to obtain an access token from the API platform. This access token is validated on every call made to the API as a representation of the client's application key and secret. This document briefly outlines the steps involved.
Authentication Step-by-Step
The steps below walk you through the process that a client uses to supply credentials and receive a token. These steps are generally the same whether you use a command-line tool like cURL or whether you bake the steps into your client application. Most programming languages, including C# and Java, provide objects that handle these steps for you, but it's worth understanding what the steps are.
Throughout this section, we will be using a command-line tool called cURL. It is used to transfer information between systems using a variety of protocols (including HTTP and HTTPS). For our purposes, it serves as a concise shorthand for the HTTP information included to make the various calls to the Ed-Fi ODS / API. Compiled executables for a variety of platforms can be downloaded from the cURL website.
Step 1. Get an Authorization Code
POST the application key to /oauth/authorize as client_id and set authorization_code to "code". You can execute a GET for this operation, although a POST is recommended.
curl https://api.ed-fi.org/v2.6.0/api/oauth/authorize -d "Client_id=RvcohKz9zHI4&Response_type=code"
Presuming you have cURL installed, the example command above should return a valid code. The URI is a publicly available sandbox instance of the Ed-Fi ODS / API hosted by the Ed-Fi Alliance and the Client ID is an OAuth key the Alliance uses for demonstration purposes. The -d switch tells cURL to POST the information in quotes.
The response will have a "Code" in the body, which represents the authorization code. The following is a sample response. You will get a different code.
{ "code": "5a531101727f4ac7b1494bb9dea544a9"}
The authorization code that is returned expires 10 minutes after being issued.
Step 2. Obtain an Access Token
At this point, clients exchange the authorization code returned in Step 1 for an access token. POST the client id, secret, and authorization code to /oauth/token as Client_id, Client_secret, and Code respectively. The Grant_type will be set to authorization_code.
The following is an example request. Replace the Code value in the snippet with the code returned in the previous step.
curl https://api.ed-fi.org/v2.6.0/api/oauth/token -H "Content-Type: application/json" -d "{'Client_id':'RvcohKz9zHI4','Client_secret':'E1iEFusaNf81xzCxwHfbolkC','Code':'R3PLAC3_W1TH_AUTH_COD3','Grant_type':'authorization_code'}"
Provided you've replaced the Code value above with a valid authorization code, the above should return an access token. In this cURL call, you'll see that we've used the -H switch to set the HTTP Content Type header to application/json, and formatted our data payload accordingly.
The snippet below shows an example response with an access token. You will get a different access token.
{ "access_token": "940934d3a405492c99572db9329fc081", "expires_in": 22199, "token_type": "bearer"}
Most platform hosts issue an access token that expires on a 30 minute sliding expiration. The sliding expiration window is extended on every operation with the API.
Step 3. Use the Access Token
On subsequent API requests, include the access token in an HTTP Authorization header as "Bearer XYZ" where "XYZ" is the access token.
The following example uses the Authorization token to retrieve the schools in the sandbox ODS / API hosted by the Ed-Fi Alliance. Replace the Bearer value with the access token returned in the previous step.
curl https://api.ed-fi.org/v2.6.0/api/api/v2.0/2018/schools -H "Authorization: Bearer R3PLAC3_W1TH_ACC3SS_TOK3N"
As another example, the following call retrieves the discipline incidents recorded in the sandbox ODS / API. Don't forget to replace the Bearer value.
curl https://api.ed-fi.org/v2.6.0/api/api/v2.0/2018/disciplineIncidents -H "Authorization: Bearer R3PLAC3_W1TH_ACC3SS_TOK3N"
You can explore the whole API surface in this manner, but there are easier ways. See the section called Using the Online Documentation for more information.
The next section, Authorization, has more details about using the access token.