Acquiring API Credentials

* If you are a student, please contact the Student Technology Council at student.tech@lists.berkeley.edu prior to requesting access. The STC sponsors all student api requests.


   Many new APIs  are becoming available to campus developers on API Central as part of the Student Information System (SIS) project. Access to them requires several fairly straightforward steps:

  1. The developer gets an account on API Central: https://api-central.berkeley.edu/
  2. The developer requests access to the particular APIs of interest by clicking the “Get Access” icon and then clicking the “Add Credentials” button specifying the API being requested (e.g. “Academic Terms”).
  3. The Data Steward approves the API request for the developer
  4. API Central generates a specific set of credentials (app_id and app_key) for the approved APIs
  5. The developer collects their credentials from API Central and uses them in their API requests

   Below, we’ll explain each of these steps and describe the applicable best practices associated along the way.

Getting an Account on API Central

   API Central uses CAS authentication for access. As a consequence, anyone with a CalNet ID automatically has an account on API Central. Simply click on the Calnet Login button on the upper right corner of the API Central page:
Image05

   That being said, the best practice is to request a CalNet Special Purpose Account (SPA), for most of SIS APIs SPA accounts are required:
https://calnetweb.berkeley.edu/calnet-departments/special-purpose-accounts-spa

   EIS strongly recommends that SPA accounts be used for any purposes, as it reduces the number of credentials that need to be managed. We recommend following these instructions for getting a new SPA account and make sure you follow these instructions to create the associated bMail account.

Requesting Access to the API

   Once you are logged in, navigate to the particular API that you want to use and click on the righthand section that shows your API Credentials.

Image03

   This will show that you do not yet have credentials. Click on the “Add credentials for this API” button to bring up a form where you will fill out your request for access to the API:

Image04

   Please make it easy for the Data Steward to decide on your request by clearly identifying who you are, why you need to use the account and any other applicable information such as:

   Once you submit the request, API Central will route your request to the appropriate parties and let them know that you have made a request. In some cases, especially when requesting access through a SPA account, it would be best to inform the Data Steward that the SPA account actually represents your request if your request doesn’t include contact information (such as email contacts) that clearly identify who you are. The Data Steward contact information is on the API Overview page under “Data Owner.”

Data Steward Approves API request

   Behind the scenes, your request will be routed to the Data Steward for that API and they will ultimately decide if they will allow access to the API. API Central and EIS provide a service to manage API requests, but we do not make decisions about who is authorized to use the APIs. You may receive further requests for information or clarification. In some situations the Data Steward may decide to only provide access to a subset of the data (for example, only data for your department, and not others).

API Central Generates Credentials for the API

   Once API access has been approved, you will be issued a set of credentials that give you access to the API. As with any credentials the following best practices apply:

   You can find all your credentials using the “My Account” tab and navigating to “My Credentials”:

Image00

   By clicking on a particular credential Name, you can see the details of the credentials, as in this example:

Image01

    The App ID is the equivalent of a username, while the App Key is the equivalent of the password. When making API queries, you can use them as the username:password in Basic Auth authentication to the API. The credentials should be passed as headers, either using the custom headers shown in the sample curl command, or using Basic Authentication. They should never be passed as part of the URL using either URL parameters or as a prefix to the hostname. Passing credentials as URL parameters or query strings simply will not work, and will compromise security, requiring a review of your access. 

Developer Uses the New Credentials

   The easiest way to test out the new credentials is to navigate to the APIs tab on API Central, select the API you want to try out, and then bring up the “Interactive Docs” display on the righthand panel (see the red arrow). You can then use the form to generate a curl request and see the resulting output. The API Central application will help you auto-populate the app_id and app_key fields with your new credentials. The example curl command will show you the API endpoint and how the parameters are embedded in the URL for the query.

   Note that in the example that follows, the app_id and app_key are put in custom headers - this is a legacy method of embedding the authentication credentials in the request, however using Basic Authentication works as just as well and is more straightforward:

Image02