API Key Component
Introduction
API keys are linked to Redwood users and allow you to use the REST Service and other inbount API connectors. You install the component which adds a new action on Redwood users, Maintain User API Keys, which allows you generated API keys and inspect which API keys the user has. For security reasons, you cannot see the value of the API key - that is only visible once, when you generate it.
New Features in 1.0.0.2
- Ability to set different expiration times on each API Key
- New Details column in the API Keys table to explain exactly when each key will expire
- Display the values for Max Expiration Time and Not Accessed Expiration Time in the UI
Prerequisites
- Platform Version 9.2.9 or greater
- Privileges Required to use API Keys
Setup
- Choose
in the tool bar. - Fill any part of the name of the component, for example
API, into the filter cell of the Name column. - Locate the component, choose Install Specific Version from the context-menu.
- Select the version you wish to install, in this example, 1.0.0.0:
- Choose Install
<version>, in this example install version 1.0.0.0.
Contents of the Component
| Object Type | Name |
|---|---|
| Application | GLOBAL.Redwood.REDWOOD.ApiKeyAuthentication |
| Extension Point | REDWOOD.Redwood_ApiKeyAuthentication |
| Library | REDWOOD.Redwood_ApiKeyAuthenticationLib |
Configuration Entries
The API Key component 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)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
- Navigate to Security > Users.
- Choose Maintain User API Keys from the context-menu of the user for which you want to maintain API keys.
- The Maintain API Keys dialog lists all API keys for the user as well as when it was used last and its expiration date.
- NOTE: All date/time values displayed in the table are shown in the time zone that is selected in the current user's User Settings in RMJ.
Table Columns
| 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 + Not Accessed Expiration 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 Not Accessed Expiration time, then a message showing the actual expiration time is shown. If the key expires before it's actual expiration date due to inactivity, a message will be shown indicating that the key expired due to inactivity. |
Creating API Keys
- Navigate to Security > Users.
- Choose Maintain User API Keys from the context-menu of the user for which you want to create an API key.
- Note: Administrators can maintain API Keys for any user. Non-Administrators can only maintain API Keys for their own user.
- Choose New API Key, and the New Key dialog will appear.
- Fill in a description in the Description field. The description must be unique.
- Select an expiration time for the key. The time shown is in the time zone that is selected in the user's User Settings in RMJ. Valid values range from the current time + 1 minute as the minimum allowed value, to the current time + the maximum expiration time defined by the MaxExpirationPeriod configuration option as the max allowed value. Choose your expiration time carefully, there is no way to extend it after the key has been created.
- Click the Generate button to create the key.
- The generated API key will be displayed, copy it to a safe location, such as a password manager.
important
You must store the API key safely, there is no way to retrieve it once the New Key dialog has been closed and a new key will have to be generated.
See Also
Introduction
API keys are linked to Redwood users and allow you to use the REST Service. You install the component which adds a new action on Redwood users, Maintain User API Keys, which allows you generated API keys and inspect which API keys the user has, for security reasons, you cannot see the value of the API key - that is only visible once, when you generated it.
Prerequisites
- Version 9.2.9
- Privileges Required to use API Keys
Setup
- Choose in the tool bar.
- Fill any part of the name of the component, for example
API, into the filter cell of the Name column. - Locate the component, choose Install Specific Version from the context-menu.
- Select the version you wish to install, in this example, 1.0.0.0:
- Choose Install
<version>, in this example install version 1.0.0.0.
Contents of the Component
| Object Type | Name |
|---|---|
| Application | GLOBAL.Redwood.REDWOOD.ApiKeyAuthentication |
| Extension Point | REDWOOD.Redwood_ApiKeyAuthentication |
| Library | REDWOOD.Redwood_ApiKeyAuthenticationLib |
Configuration Entries
The API Key component supports the following configuration entries:
| Configuration Entry | Description | Default Value | Maximum 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)y - year(s) | p3m (three months) | p1y (1 year) |
/configuration/jcs/apps/ApiKey/MaxExpirationPeriod | The period after their creation time when API keys are expired. | p6m (6 months) | p1y (1 year) |
tip
Periods are specified in ISO 8601 format (in lower case).
Managing API Keys
View API Keys
- Navigate to Security > Users.
- Choose Maintain User API Keys from the context-menu of the user for which you want to maintain API keys.
- The Maintain API Keys dialog lists all API keys for the user as well as when it was used last and its expiration date.
Creating API Keys
- Navigate to Security > Users.
- Choose Maintain User API Keys from the context-menu of the user for which you want to create an API key.
- Choose New API Key, fill in a description in the Description field and choose Generate.
- The generated API key will be displayed, copy it to a safe location, such as a password manager.
important
You must store the API key safely, there is no way to retrieve it once the New Key dialog has been closed and a new key will have to be generated.