
	Version 9.6	SEARCH CONTENTS \| PDF BOOKS \| HOME UP PREV NEXT

— API Management Solutions —

Managing API Keys and OAuth 2.0 Tokens

This section describes to how an API Provider (owner) can manage API keys and OAuth2 tokens.

To manage the various operations (Generate, Renew, Revoke or Delete) on an API key or OAuth token, you must belong to a role that has the "Modify Assets" permission for the organization in which the API resides. Else, at least have the Full instance-level permission on the API itself. However, if you belong to a role that has the "Manage Assets" permission, you can configure the consumption settings for APIs in all organizations. To see a list of the predefined roles that include the "Manage Assets" or "Modify Assets" permission, see the section About Roles and Permissions in the document Users, Groups, Roles and Permissions.

The following sections describe how to manage your API keys and OAuth tokens.

Satisfying Key and OAuth Token Generation Requirements
Renewing an API Key
Revoking an API Key
Deleting an API Key

Satisfying Key and OAuth Token Generation Requirements

For a user to consume an API with the API key or an OAuth token, the following prerequisites must be met:

Ensure that you have configured the API Consumption Settings so that the API is configured for either API key authentication or OAuth2 authentication, as described in Configuring the API Consumption Settings.
Ensure that a run-time target instance (for example, Mediator) is up and running. For information on targets, see the section Run-Time Targets.

The API provider (and users who belong to a role with the permissions stated above) can satisfy the prerequisites.

Sometimes you might have to require an approval to generate an API key or OAuth token. If you selected the Require Approval option when you configure the API's consumption settings, CentraSite will not generate the API key or OAuth token until the required approvals are obtained. However, if an approval workflow is not configured for the API, the key or OAuth token is generated.

Once the API key or OAuth 2.0 request is approved by the designated approvers, an email notification is sent to both the API provider and API consumer.

CentraSite provides predefined email templates intended to be used for the API key or OAuth token generation. By default, these templates are configured in the centrasite.xml file. But, if you do not want to use the predefined email templates, you can create your own templates and configure the centrasite.xml file as necessary. For more information on how to configure the email templates for API key or OAuth token generation, see the following section Configuring the email templates for API key or OAuth token generation.

For more information on how to configure the email notifications for API key or OAuth token generation in the CentraSite Business UI, see Configuring the API Consumption Settings .

Configuring the Email Templates for API Key or OAuth Token Generation

Notifications informing details and usage of the new API key or OAuth token are generated and sent to both the API provider and API consumer.

There are three kinds of key generation notifications:

An API key or OAuth token request is pending for approval - an information type message to the API provider.
Your API key or OAuth token request is approved - an information type message to the API consumer.
Your API key or OAuth token request is rejected - an information type message to the API consumer.

You can configure delivery of such notifications in the centrasite.xml configuration file.

To configure notifications for API key or OAuth token generation

Use a text editor to open the centrasite.xml file for the API key or OAuth token generation notifications, which is typically located in the <CentraSiteInstallDir>\cast\cswebapps\BusinessUI\ directory.

Locate the KeyGenerationSettings element in the file.

The key generation notification settings would look like the following:

<KeyGenerationSettings>
   <Approve subject="CS_MSG_INMBU_DEFAUL_EMAIL_SUBJECT_ACCESS_KEY_GENERATION_SUCCESS_OR_APPROVE" template="APIKeyGenerationSuccess.html" />
   <ApprovalRequest subject="CS_MSG_INMBU_DEFAUL_EMAIL_SUBJECT_ACCESS_KEY_GENERATION_PENDING" template="PendingApprovalNotification.html" />
   <Reject subject="CS_MSG_INMBU_DEFAUL_EMAIL_SUBJECT_ACCESS_KEY_GENERATION_REJECT" template="RejectionNotification.html" />
</KeyGenerationSettings>

Uncomment the section API Key Settings to enable key generation notifications.
Use the Approve property to set the subject and body of the notification message for the consumers whose API key or OAuth token request is approved.
Use the ArppovalRequest property to set the subject and body of the notification message for the provider who has an API key or OAuth token request pending for approval.
Use the Reject property to set the subject and body of the notification message for the consumers whose API key or OAuth token request is rejected.
Save and close the file.
Restart Software AG Runtime.

Renewing an API Key

After an API key is generated, sometimes you might have to renew the old key due to expiration or security concerns. You can also change expiration period for the API key or set it so that the key never expires.

The API provider (and users who belong to a role with the permissions stated above), can renew an API key.

Note:
The Renew option is not available for the OAuth 2.0 tokens.

To renew an API key, the following prerequisites must be met:

Ensure that you have configured the API Consumption Settings so that the API is configured for either API key authentication or OAuth2 authentication, as described in Configuring the API Consumption Settings.
Ensure that a target instance (for example, Mediator) is up and running. For information on targets, see the section Run-Time Targets.

The API provider (and users who belong to a role with the permissions stated above), can renew an API key.

To renew an API key

In CentraSite Business UI, display the details page for the API whose key you want to renew. For procedures, see the section Viewing Details of an API.
Locate the hyperlinked text "N" Consumers in the description area of the Basic Information profile, for example, "N" Consumers.
Click on the hyperlinked number "N" to see the list of keys available for the API.
Click on the hyperlinked API key name to see more information about who consume the API.
Review expiration date of the API key. A value of "Unlimited" indicates that the key never expires.
Locate the API key you want to renew.
Mouse over the API key name, and click on the Renew icon displayed to the right hand side.

Important:
If the API key has an unlimited expiration period, the Renew icon is NOT visible in the user interface.

Changing the Default Key Expiration Interval

API keys have a default expiration period, which you specify when you configure the API key consumption settings.

You can also change expiration period for the API key or set it so that the key never expires.

Sometimes you might have to require an approval to renew (refresh) the API key. If you selected the Require Approval option when you configured the API key consumption settings, CentraSite will not renew the API key until the required approvals are obtained. However, if an approval workflow is not configured for the API, the key is renewed instantly. For more information about approval actions, see the section Working with Approval Workflows in the document Administering the CentraSite Business UI.

Once the API key renewal request is approved by the designated approvers, an email notification informing the new validity of API key is sent to both the API provider and API consumer.

CentraSite provides predefined email templates only intended for the API key renewal. By default, these templates are configured in the centrasite.xml file. But, if you do not want to use the predefined email templates, you can create your own templates and configure the centrasite.xml file as necessary. For more information on how to configure the email templates for API key renewal, see the following section Configuring the email templates for key renewal.

The API key with the new validity is republished to the Mediator, triggered by a Deploy API Key action that is included in the API Key Renewal policy.

For more information on how to configure the email notifications for API key renewal in the CentraSite Business UI, see Configuring the API Consumption Settings.

Configuring the Email Templates for Key Expiration

Notifications informing about upcoming API key expiration and generated API key expired are generated and sent to the API consumer.

A consumer can have two kinds of key expiration notifications:

API key has expired - a critical event type message.
API key expires soon - a warning type message. It will be generated "n" days before the key expiration date and displayed every day before the key actually expires.

You can configure delivery of such notifications in the centrasite.xml configuration file.

To configure templates for API key expiration

Use a text editor to open the centrasite.xml file for the key expiration notifications, which is typically located in the <CentraSiteInstallDir>\cast\cswebapps\BusinessUI\ directory.

Locate the ExpiryNotificationSettings element in the file.

The expiration notification settings would look like the following:

<ExpiryNotificationSettings>
  <ExpiredNotification subject="Access key has expired!" template="APIKeyExpiredNotification.html" />
  <AdvanceNotification subject="Access key about to expire!" template="APIKeyExpirationNotification.html" />
  <SchedulerExecutionFrequency>12h</SchedulerExecutionFrequency>
  <AdvanceNotificationInterval>5d</AdvanceNotificationInterval>
</ExpiryNotificationSettings>

Uncomment the section API KEY EXPIRATION CONFIGURATION to enable key expiration notifications.
Use the ExpiredNotification property to set the subject and body of the notification message for the consumers whose API key has expired.
Use the AdvanceNotification property to set the subject and body of the notification message for the consumers whose API keys are due to expire.
Use the SchedulerExecutionFrequency attribute to specify how frequently to check for the expiration status of API keys. Enter the time interval in the following format: years (y), months (m), days (d), hours (h), minutes (min).
Use the AdvanceNotificationInterval attribute to specify how many days should be consumers notified before the key expiration (in days). Then the consumers are entitled receive a notification message as configured in the AdvanceNotification property. Enter the time interval in the following format: years (y) months (m) days (d) hours (h) minutes (min).
Save and close the file.

Important:
If you have set up a Software AG Runtime cluster with load balancing, locate the CENTRASITE ACCESS URL CONFIGURATION element, and ensure that the lb_or_reverse_proxy_url attribute in the following property points to the load balancer's IP/Port.
```
<CentraSite url="http://localhost:53305/CentraSite/CentraSite" lb_or_reverse_proxy_url="http://localhost:53307"/>
```
Restart Software AG Runtime.

Configuring the Email Templates for Key Renewal

Notifications informing the new validity of the API key are generated and sent to both the API provider and API consumer.

There are three kinds of key renewal notifications:

An API key renewal request is pending for approval - an information type message to the API provider.
Your API key renewal request is approved - an information type message to the API consumer.
Your API key renewal request is rejected - an information type message to the API consumer.

You can configure delivery of such notifications in the centrasite.xml configuration file.

To configure email templates for API key renewal

Use a text editor to open the centrasite.xml file for the key renewal notifications, which is typically located in the <CentraSiteInstallDir>\cast\cswebapps\BusinessUI\ directory.

Locate the KeyRenewalSettings element in the file.

The key renewal notification settings would look like the following:

<KeyRenewalSettings>        <Approve subject="CS_MSG_INMBU_DEFAUL_EMAIL_SUBJECT_ACCESS_KEY_RENEWAL_SUCCESS_OR_APPROVE" template="APIKeyRenewalSuccess.html" />        <ApprovalRequest subject="CS_MSG_INMBU_DEFAUL_EMAIL_SUBJECT_ACCESS_KEY_RENEWAL_PENDING" template="APIKeyRenewalPendingNotification.html" />        <Reject subject="CS_MSG_INMBU_DEFAUL_EMAIL_SUBJECT_ACCESS_KEY_RENEWAL_REJECT" template="RejectionNotification.html" />      </KeyRenewalSettings>

Uncomment the section API Key Settings to enable key renewal notifications.
Use the Approve property to set the subject and body of the notification message for the consumers whose API key renewal request is approved.
Use the ArppovalRequest property to set the subject and body of the notification message for the provider who has an API key renewal request pending for approval.
Use the Reject property to set the subject and body of the notification message for the consumers whose API key renewal request is rejected.
Save and close the file.
Restart Software AG Runtime.

Revoking an API Key

After issuing an API key, you might want to revoke the key if you find serious error in the API. When you revoke an API key, client access to the associated API is blocked, and the client that is assigned that key can no longer access the resources exposed by that API.

The API provider (and users who belong to a role with the permissions stated above), can revoke an API key.

Note:
The Revoke option is not available for the OAuth 2.0 tokens.

To revoke an API key, the following prerequisites must be met:

Ensure that you have configured the API Consumption Settings so that the API is configured for either API key authentication or OAuth2 authentication, as described in Configuring the API Consumption Settings.
Ensure that a target instance (for example, Mediator) is up and running. For information on targets, see the section Run-Time Targets.

To revoke an API key

In CentraSite Business UI, display the details page for the API whose key you want to revoke. For procedures, see the section Viewing Details for an API.
Locate the hyperlinked text "N" Consumers in the description area of the Basic Information profile, for example, "N" Consumers.
Click on the hyperlinked number "N" to see the list of keys available for the API.
Click on the hyperlinked API key name to see more information about who consume the API.
Locate the API key you want to revoke.
Mouse over the API key name, and click on the Revoke icon displayed to the right hand side.

A confirmation message appears that the API key will be revoked.

Once the API key revocation is processed, CentraSite sends an email message to the API consumer informing that the request has been processed successfully.

CentraSite provides predefined email template only intended for the API key revocation. By default, this template is configured in the centrasite.xml file. But, if you do not want to use the predefined email template, you can create your own template and configure the centrasite.xml file as necessary. For more information on how to configure an email template for API key revocation, see the following section Configuring the email notification for key revocation.

For more information on how to configure an email notification for API key revocation in the CentraSite Business UI, see Configuring the API Consumption Settings.

Configuring the Email Notification for Key Revocation

Notification informing the successful processing of an API key revocation is sent to the API consumer.

You can configure delivery of such notification in the centrasite.xml configuration file.

To configure email templates for API key revocation

Use a text editor to open the centrasite.xml file for the key revocation notification, which is typically located in the <CentraSiteInstallDir>\cast\cswebapps\BusinessUI\ directory.

Locate the KeyRevocationSettings element in the file.

The key revocation notification settings would look like the following:

<KeyRevocationSettings>
  <Approve subject="CS_MSG_INMBU_DEFAUL_EMAIL_SUBJECT_ACCESS_KEY_REVOCATION_NOTIFICATION" template="APIKeyRevocationSuccess.html"/>
</KeyRevocationSettings>

Uncomment the section API Key Settings to enable key revocation notifications.
Use the Approve property to set the subject and body of the notification message for the consumers whose API key revocation request is processed successfully.
Save and close the file.
Restart Software AG Runtime.

Deleting an API Key

Deleting an API key permanently removes the entry for the API key (that is, it removes the instance of the API key from the CentraSite registry/repository). Deleting an API key will not remove the API that is associated with it.

The API provider (and users who belong to a role with the permissions stated above), can delete an API key.

When you delete an API key, keep the following points in mind:

You cannot delete an API key that is in the “pending” mode (example, awaiting a renew approval).
Deletion of an API key will succeed only if the key is already revoked.

To delete an API key

In CentraSite Business UI, display the details page for the API key that you want to delete. If you need procedures for this step, see the section Viewing Details for an API.
On the API key’s actions menu, click Delete .
When you are prompted to confirm the delete operation, click Yes.

The API key is permanently removed from the CentraSite registry.

You can delete multiple API keys in a single step. The rules described above for deleting a single API key apply also when deleting multiple API keys.

Important:
A key must be revoked before it can be deleted.

To delete multiple API keys in a single operation

In CentraSite Business UI, use either the Browse or Search feature to select a set of API keys you want to delete. If you need information on how to browse or search the Business UI, refer to the section Browsing the CentraSite Catalog or Searching the CentraSite Catalog in the document Managing the CentraSite Catalog.
Mark the checkbox next to the name of each API key you want to delete.
In the actions menu, click Delete .

Note:
If one or more or the selected API keys are in pending mode (example, awaiting approval), an error message will appear and no API key will be deleted.

SEARCH CONTENTS | PDF BOOKS | HOME UP PREV NEXT