API Key Extension 1.0.0.3

API keys let you use the REST Service and other inbound API Exetnsions. Each API key is specific to a particular user.

New Features in 1.0.0.3

  • When you create an API key, you can now set up a notification to alert you at a particular date and time. This lets you make sure that you regenerate the API key before it expires.

Prerequisites

Setup

To set up the API Key Extension, locate API Key Authentication in the Catalog and install it.

Contents

Object Type Name
Application GLOBAL.Redwood.REDWOOD.ApiKeyAuthentication
Extension Point REDWOOD.Redwood_ApiKeyAuthentication
Library REDWOOD.Redwood_ApiKeyAuthenticationLib

Registry Keys

The API Key Extension supports the following Registry keys.

Configuration Entry Description Default Value
/configuration/jcs/apps/ApiKey/MaxExpirationPeriod The maximum lifetime for an API key. This value displays as Max Key Lifespan in the Maintain API Keys window. p6m (6 months)
/configuration/jcs/apps/ApiKey/NotAccessedExpirationPeriod API keys expire if they are not used within a particular period of time. This period is expressed as p<number><unit>, where <number> is the number of <units> and <unit> is a duration: d = days, w = weeks, m= months, and y = years. This value displays as Not Accessed Expiration in the Maintain API Keys window. p3m (three months)

Tip: Periods are specified in ISO 8601 format (in lower case).

Creating API Keys

To create an API key for a particular user:

  1. If you want to set up a notification for the API Key, create an Ad Hoc Alert Source to use later in setting up the notification. You can configure the Ad Hoc Alert Source to raise a custom Operator Message or send an email.

    Note: This step is not required while creating the API Key. You can always edit the API Key later to set up the notification, as long as it has not expired.

  2. Navigate to Security > Users.

  3. Right-click the user and choose Maintain User API Keys. Note that administrators can maintain API Keys for any user, but non-Administrators can only maintain their own API Keys.

  4. Click New API Key. The New API Key overlay displays.

  5. Enter a description in the Description field. The description must be unique.

  6. In the Expires At field, specify an expiration date and time for the key. The time shown is in the time zone that is selected in User Settings. Valid values range from the current time + 1 minute to the current time + the maximum expiration time defined by the MaxExpirationPeriod configuration option. Choose your expiration time carefully, there is no way to extend it after the key has been created.

  7. If you want to be notified at a particular date and time (for example, shortly before the API key's expiration date):

    1. Check Notification.

    2. Specify the time you want to be notified in the Time field.

    3. Select the Ad Hoc Alert Source you created in step 1 from the Alert dropdown list.

  8. Click Generate.The generated API key is displayed for the first and only time.

  9. Copy the API key to a safe location such as a password manager.

Warning: There is no way to retrieve an API key once the New API Key overlay has been closed.

Viewing and Editing API Keys and Notifications

To view or edit API keys and the associated notifications for a User:

  1. Navigate to Security > Users.

  2. Right-click the User and choose Maintain User API Keys. The Maintain API Keys dialog displays.

  3. To create a notification for an API Key, click in the Notification column. To edit an existing notification, click . To remove the API Key, click in the Remove column.

Column Name Description
Description The description given to the key when it was created
Creation Time The date and time that the key was created
Last Used Time The last date and time that the key was used by any application. NOTE: This value will only update once per minute, even if the key was used multiple times during that minute.
Expiration Time The expiration time that was defined when the key was created.
Details Additional details about the key expiration. If the Last Used Time + NotAccessedExpirationPeriod value is earlier than the Expiration Time, it will show the date/time that the key will automatically expire if it is not used again. If the defined Expiration Time is earlier than the NotAccessedExpirationPeriod time, then a message showing the actual expiration time is shown. If the key expires before its Expiration Time due to inactivity, a message is displayed, indicating that the key expired due to inactivity.
Notification Click to add a notification, or to edit an existing notification.
Remove Click in this column to delete the API key.

Notes About Notifications

  • Each API Key can only have one notification scheduled.

  • When you create a notification, a System_Alert_Send Process is automatically scheduled to send the Ad Hoc Alert at the date and time you specified.

  • If you change the notification time or update the Ad Hoc Alert for the API key before the System_Alert_Send Process starts, RunMyJobs automatically updates the System_Alert_Send Process. If the System_Alert_Send Process has already started, RunMyJobs schedules a new System_Alert_Send Process and tracks that one instead.

  • You can cancel the notification by editing the API key. This will set the status of the scheduled System_Alert_Send Process to Canceled.

  • If you cancel or delete the scheduled System_Alert_Send Process, the notification is also canceled.