* If you are a student, please contact the Student Technology Council at firstname.lastname@example.org 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:
- The developer gets an account on API Central: https://api-central.berkeley.edu/
- 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”).
- The Data Steward approves the API request for the developer
- API Central generates a specific set of credentials (app_id and app_key) for the approved APIs
- 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.
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:
That being said, the best practice is to request a CalNet Special Purpose Account (SPA), for most of SIS APIs SPA accounts are required:
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.
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.
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:
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:
- Whether you already have access to the same data using another integration method
- Whether you have appropriate Data Protection Level for the data https://security.berkeley.edu/data-classification-standard
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.”
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).
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:
- Do not share your credentials with others who are not authorized for access
- Manage your credentials securely:
- Do not leave them in public readable locations, such as:
- Embedding them in source code that is in a Github repo or an SVN repository that has public, anonymous access.
- Embedding them in a script that is publicly readable on a shared computer
- If you are making API requests using these credentials, you should always be using an SSL encrypted endpoint
You can find all your credentials using the “My Account” tab and navigating to “My Credentials”:
By clicking on a particular credential Name, you can see the details of the credentials, as in this example:
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.
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: