Products & Services / I-Share / External System Integrations / How to: Request or Create an API Key for Alma and Primo VE
Related product I-Share

How to: Request or Create an API Key for Alma and Primo VE

Alma and Primo VE may be integrated with several different third party applications. Some of these applications will require that you create an API key to secure communication between the application and Alma. API keys are configured in the Ex Libris Developer Network, and this configuration may be performed by CARLI staff or by staff at your institution.

Every institution should have at least one staff member with a Developer Network account. Typically, this will be the I-Share Liaison, but other staff may also have accounts. If your I-Share Liaison or other technical staff do not have Developer Network accounts, see CARLI's page on Requesting a Developer Network Account, and contact CARLI support for an invitation.

Pre-requisites

Alma and Primo VE provide hundreds of REST APIs that may be used to retrieve data from and send data to Alma and Primo VE. Access to these REST APIs is controlled through an API key, a long string of characters that is unique to your institution and to the parts of Alma that you allocate to that key. It is a best practice to configure each API key as narrowly as possible for the application and key to do their jobs.

Before creating an API key, you will need to identify some details about the application and what the application needs from Alma or Primo VE. Some of this information is valuable for your own record-keeping and accountability, and some is necessary to configure the key. If you are requesting that CARLI create the API key for you, please have all of this information available.

  • Name of the application and developer
  • Whenever possible, identify which specific areas and permissions are needed.
    • API areas are:
      • Acquisitions (includes vendors, orders, invoices, funds, licenses)
      • Analytics
      • Bibliographic Records and Inventory (includes bibs, holdings, items)
      • Courses
      • Electronic Resources (includes collections, services, portfolios)
      • Resource Sharing Partners
      • Task Lists
      • Users and Fulfillment
      • Primo (has 11 types of keys)
    • Permission sets are:
      • Read-only (your application only needs to get data)
      • Read-write (your application needs to get data and add new data or modify existing data

If the specific areas aren't explicitly mentioned in the application documentation, identify what data the application needs from Alma. Knowing how the application works may inform you and CARLI how the API key should be configured.

In many cases, you may be able to find documentation on the Developer Network about existing integrations created by other Alma institutions or profiled by Ex Libris staff. It's also possible that you may need to confer with the application developer or provider for details if such information is not easily found online.

Logging On to the Developer Network

  1. Connect to the Ex Libris Developer Network site.
  2. Click the Login link in the upper right corner.
  3. Enter your email address and your Developer Network account password. Note: Your Developer Network account is separate from your Alma account, and your password may be different depending on what you chose when you created the account. If you don't remember your password, click the Lost Password link.

Key Creation

This section covers the general steps for creating a new API key using an example scenario: Creating an API key for ILLiad's "Alma Barcode Lookup" add-on. If you have a developer network account for your institution, you may create a key in this manner. CARLI staff will follow these steps as well in creating a key.

Note: The Ex Libris Developer Network is presented using responsive web design. Some site and menu options change depending on the width of the browser screen. If the screen is narrow or you are using a mobile interface, you will see different choices.

  1. When you are logged in, click the Build My APIs option.
    An image of the Ex Libris Developer Network, logged in to the My Account screen. The Build My APIs link is highlighted with a purple rectangle.
    If you are viewing the Developer Network in a narrow screen or mobile browser, click the menu in the top left, then select My APIs.An image of the Ex Libris Developer Network my account page, as viewed in a mobile browser. The menu is open from the top left, and the My APIs option is highlighted with a purple rectangle.
  2. Click the Manage Keys button under API Keys.
    An image of the Ex Libris Development Network Build APIs page. The Manage Keys button is highlighted with a purple rectangle.
  3. CARLI has already created some API keys for every institution. You will see those and any that your institution has created on the Manage API Keys screen. Note that some keys cover a single area, and other keys include multiple areas with different permissions.
    An image of the Ex Libris Developer Network manage API keys screen for a CARLI institution. Five keys have been created with different configurations. There is an Add API Key button below and to the left of the existing keys.
  4. Click Add API Key.
  5. Enter the name for the key; we recommend including the application and expected use as the name. For example, "ILLiad Add-on: Alma Barcode Lookup."
  6. Optionally, add a description to provide more information. The name and description are used by library staff and CARLI, so make them useful for future users.
  7. Under permissions, click Add Permission to create a row for an API area. Repeat for each area needed for the API key.
    An image of the Ex Libris Developer Network screen for Add/Edit API key. This screen includes fields for Name, Description, Enabled, Save detailed log files, Allowed IP range, Restriction profile code, and a permissions area. An Add Permission button is below and left of the permissions area, and a save button is visible below and right of the permissions area.
  8. Click the Area list to select which area to provision. In this example, we need "Bibs" for the bibliographic and inventory area, which allows lookup of barcode data from item records.
  9. Select the environment of Production. Your account may also have options for "Sandbox" or "Guest Sandbox." CARLI will advise you when these might be preferable.
  10. Select permissions appropriate to what the application will do with the data. In this example, the ILLiad add-on requests item information, so it needs read-only permissions only.
  11. Repeat steps 7-10 as needed, or click Save when finished.
  12. The new key will be added to the list of managed keys.

Key Retrieval

When you configure a third party application to work with Alma APIs, you may typically have a configuration screen in that application or website that needs the API key. The most efficient, and most secure method of adding the key is for you to copy the key from the Developer Network and paste into the application configuration. It is considerably less secure to send API keys via email, since email is not 100% secure. Whenever possible, CARLI recommends that the I-Share Liaison or other appropriate staff maintain an active Developer Network account to retrieve keys using the following steps.

  1. Navigate to the Manage API Keys screen as described above.
  2. Locate the API Key name that was created above (e.g., ILLiad Add-on: Alma Barcode Lookup).
  3. Under the column labeled API Key, look into the box for the key that was created, and click the *eye* icon in order to reveal the key.
    An image of a portion of the Manage API Keys screen that shows a toggle for the key that is active, the name of the key, and the key value. An icon resembling an open eye is highlighted with a purple rectangle.
  4. After clicking the icon, the key value will be partially visible, and the Copy button will become active. Click Copy to clip the key value.
  5. Paste that value into the application that needs the key.

Retrieving Keys When You Don't Have a Developer Network Account

If you do not have a Developer Network account, and you would like an alternative to retrieving keys directly in the Developer Network, you may arrange with CARLI to get your API key through a document in your institution's Box.illinois.edu folder.