API Key Extension 1.0.0.2

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

New Features in 1.0.0.2

  • You can now set different expiration times for different API keys.
  • The new Details column lets you see exactly when each key will expire.
  • The values for Max Expiration Time and Not Accessed Expiration Time are now displayed in the UI.

  • Removed 1 year maximum value for NotAccessedExpirationPeriod and MaxExpirationPeriod configuration entries.

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

Configuration Entries

The API Key Extension supports the following configuration entries:

Configuration Entry Description Default Value
/configuration/jcs/apps/ApiKey/NotAccessedExpirationPeriod The period after their last used time when API keys are expired. Periods are expressed as p<number><unit>, where <number> is the number of <units> and <unit> is a duration: d = day(s), w = week(s), m=- month(s), and y = year(s) p3m (three months)
/configuration/jcs/apps/ApiKey/MaxExpirationPeriod The period after their creation time when API keys are expired. p6m (6 months)

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

Managing API Keys

View API Keys

  1. Navigate to Security > Users.
  2. Choose Maintain User API Keys from the context menu of the user for which you want to maintain API keys.
  3. The Maintain API Keys dialog lists all API keys for the user as well as when it was used last and its expiration date.
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.

Creating API Keys

To create an API key for a particular user:

  1. Navigate to Security > Users.
  2. 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.
  3. Click New API Key. The New API Key overlay displays.
  4. Enter a description in the Description field. The description must be unique.
  5. Select 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.
  6. Click Generate.The generated API key is displayed for the first and only time.
  7. 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 Key overlay has been closed.