Authorization

Authorization takes place after authentication is established. If you're reading this, you probably already know that the purpose of authorization is to establish a particular user has rights to work with a particular system function or a specific piece of information. This section describes the fundamentals of authorization in connecting with an Ed-Fi API. The core concepts to understand are how tokens and profiles are used.

Tokens & Profiles

With each request made to the API, the token obtained from the authentication process must be passed in an HTTP¹ header, like so:

Authorization: Bearer <token_value>

The Ed-Fi API uses this token to identify the caller and determine the permissions that apply to each of the accessible API resources.

Additionally, different authorization strategies are used for different API Resources. For many resources, a relationship-based strategy will be used. For example, a SIS vendor will be provided with an API key that is associated with a specific school or local education agency. When accessing the “students” resource, they will only be able to read and write data for students that are registered at their school, or at a school within the associated local education agency. An ownership-based authorization strategy is used for assessment metadata, enabling multiple callers to create and manage their own metadata.

API Profiles enable an Ed-Fi ODS / API platform host to constrain the data exposed from specific resources to meet the needs of individual use cases. Callers that have been assigned a profile must use that profile when accessing the affected resources.

To use a profile, callers must add media type information to their requests. For read operations this takes the form of an Accept header, shown below, which indicates to the server that the caller will accept the profile-based version of the resource.

Accept: application/vnd.ed-fi.student.nutrition.readable+json

For write operations, the Content-Type header is used.

Content-Type: application/vnd.ed-fi.student.nutrition.readable+json

This indicates to the server that the caller is expecting their update to apply to the constrained surface area of the Resource as defined by the Profile. With this explicit communication style, any extra data passed in the message body can (and generally will) be quietly discarded by server.

While callers can choose to use any Profile, failure to use an assigned Profile (e.g., using the application/json media type) will result in an error.

Now that you've seen how to authenticate and authorize a client application, let's look at how to build one. The next section walks you through the details.

¹ Throughout this documentation, we generally use "HTTP" to describe specific uses of that protocol. As noted elsewhere, the traffic between systems containing production data is always over HTTPS.