Faculty180 API HMAC Examples

Overview

This repository contains additional code samples of using the Interfolio Faculty180 Application programming interface (API) with Hash-based Message Authentication Code (HMAC) authentication beyond those provided by Interfolio in their HMAC documentation.

API Access Control (HMAC)

For authentication, Interfolio uses the HMAC mechanism. For authorization, Interfolio uses the tenant ID and a permissioning infrastructure that determines if the user has permission to access a particular set of data. API authorization requires a properly formatted HTTP request header.

Three Informations

There are three pieces of information required for successful authentication and authorization:

1. public key (example):
   • Y5aNy8OZRYFKlTxNzXuSxzz64M8YLQB3vrcUP1zk7wQ=
2. secret key (example):
   • uEvu95GRt8fYw8dZkOyQGsOLy5yuB9vcUEK5cAcNuB4X6D6pTJegoIp/yRa7GaP/Lf6CQIA/xI/oP//YkayuAByx0nieazUEqp3DR7FtNf43=
3. database id (example):
   • TestUniv

Note: this is an example key-pair. Interfolio will provide unique key-pairs.

Process

1. Determine what API(s) you want to call (URL string)
2. Create a valid timestamp string in UTC (GMT)
3. Create a verb string composed of:
   • The verb for the request you want to perform (GET, POST, PUT, DELETE)
   • Three ASCII newlines
   • The timestamp string
   • Another ASCII newline
4. Take all of the content after 'faculty180.interfolio.com/api.php' from the URL string (this is the request string)
5. Create the verb request string composed of:
   • The verb string
   • The request string
6. Create an encrypted string by HMAC_SHA1 encoding your verb-request string with your secret key.
7. Base64-encode the encrypted string (this is the signed hash)
8. Submit your request to your URL string with the following authorization header and timestamp header:
   • TimeStamp: properly formatted timestamp
   • Authorization: INTF Your public key + Your signed hash
   • INTF-DatabaseID: your institution's database ID (e.g. TestUniv)

Examples

The Faculty180 HMAC documentation can be found here, but the code examples provided are only in PHP, Ruby, and Python 2.

This repository contains a copy of the Python 2 example as well as a port to Python 3 and R.

About

Saint Louis University

Founded in 1818, Saint Louis University is one of the nation’s oldest and most prestigious Catholic institutions. Rooted in Jesuit values and its pioneering history as the first university west of the Mississippi River, SLU offers nearly 13,000 students a rigorous, transformative education of the whole person. At the core of the University’s diverse community of scholars is SLU’s service-focused mission, which challenges and prepares students to make the world a better, more just place.