Administering Sierra API Client Keys

Sierra API client key administration enables you to create, edit, refresh, and delete client keys for Sierra REST API access. The Sierra API Keys page presents a list of existing client keys with the following information:

Creating a New Client Key

To create a new client key:

1. In the Sierra Administration application, click Sierra API Keys from the Other Web Applications group.
2. On the Sierra API Keys administration page, click CREATE NEW. The Create New API Key page opens.
3. Enter the Client name.
4. Enter the Client Email address.

5. Specify an expiration date in the format M/D/YY or select No Expiration.
6. (Optional) To retrieve or update specific patron accounts only, do the following:
   1. Select the Patron-specific Authentication option.
   2. Enter a redirect URL to associate with the key.

For more information about this option, see Patron Permission - Patron-Specific Authentication below.

7. In the Roles section, select the API read/write permissions to authorize for the key. See Roles below for information on which endpoints are associated with each role.
8. Click GENERATE API KEY. The New API Key page opens.
9. Review the API key client information, and then select one of the following:
   1. Done - Returns to the Sierra API Keys page.
   2. Generate another - Returns to the Create New API Key page.
   3. Edit this record - Opens the API Key Info page in which you can edit the client name, email address, and status.

Editing or Deleting an Existing Client Key

To edit an existing client key:

1. On the Sierra API Keys administration page, click the client you want to edit. (The client name is a link.) The API Key Info page opens.
2. Click EDIT. You can then:
   • Change the client name.
   • Change the client email address.
   • Reset the API key. (Resetting the API key sends a new verification email.)
   • Enable or disable the API key.
   • Specify a new expiration date for the client key.
3. Click SAVE to preserve your changes or Discard Changes to cancel your edits.
4. (Optional) Click Delete Record if you want to remove the client key from the system.

Creating a Client Secret

When Sierra generates the API Key, it sends a verification email to the specified address. To complete the registration, the client must do the following within one week of receiving the registration email:

1. Click the Continue Registration link in the verification email. The link verifies the client email address and directs the default browser to the API Key Registration webpage.

2. Enter and confirm a client secret that is at least eight characters.
3. Click Register.

Upon successful registration, a Registration Complete notice appears. The notice includes both the API Key and the API Client Secret.

Refreshing an Existing API Key

New permissions are occasionally added to existing roles with new releases of Sierra. Rather than regenerating or creating a new key, you can refresh the key to pick up any new permissions associated with the role(s) assigned to that key.

To refresh a key:

1. On the Sierra API Keys administration page, click the client you want to edit. (The client name is a link.) The API Key Info page appears.
2. Click EDIT.
3. Select Expiration Date, and enter an expiration date.
4. Click SAVE.
5. Edit the key again.
6. Select No Expiration.
7. Click SAVE.

Sierra refreshes the key.

API Access Keys Permissions and Roles

Patron Permissions and Roles are used to manage the patron data access level permissions for API keys. Some additional details about these settings are provided below.

Patron Permission - Patron-Specific Authentication

This option requires the API consumer to redirect the user to the Innovative authentication service for authentication and, when authentication is successful, the Sierra REST API redirects the user back to the API consumer’s interface through the redirect URL. When enabling this option, a redirect URL is required to complete the process.

The Patrons Read and Patrons Write permissions allow the API consumer to retrieve and/or update any patron's account information.

Roles

Specifies the API read/write permissions authorized for the key. The following list identifies the available roles and associated API endpoints: