Configuring the API Consumption Settings for API Key Authentication
In this task, you configure the following characteristics for granting API keys:
Specify the approval requirements for clients requesting API keys.
You can specify that requests must be approved by approver groups of your choosing, or you can specify that requests will be automatically approved.
Configure email messages to be sent to:
The approver groups when requests are submitted for approval.
The clients to inform them of their approval status.
Specify the expiration of the API key.
Clients that want to use the API key to call (consume) an API in CentraSite must:
1. Register as a consumer for the API, as specified in Run-Time Governance with CentraSite.
When the client registration request is approved, the client receives an API key (a base64-encoded string of the consumer-key:consumer-secret combination). It works for both SOAP and REST calls.
2. To call the API, the client must pass the API key in an HTTP request header or as a query string parameter. The use of this key establishes the client's identity and authentication.
For information about how consumers will use generated API keys, see Run-Time Governance with CentraSite.
To configure the API Consumption Settings for API key authentication
1. In CentraSite Business UI, display the details page for the API whose key settings you want to configure. For procedures, see Viewing Details for an API. 2. In the actions bar for the API, click API Consumption Settings.
3. In the API Consumption Settings dialog, select API Keys.
You might wish to modify the authentication type for an API at a later stage. When modifying the authentication type (say, OAuth2), if the API has one or more API keys generated using the currently configured authentication mechanism, CentraSite issues a warning message.
The message states that the modification to the configured authentication mechanism would deactivate all of the existing API keys that were generated using the authentication mechanism that you now intend to modify.
4. In the Usage Contract Expires After field, type a time interval that represents how long you wish the API key to be active before it expires. Type the time interval in the following format: years (y) months (m) days (d) hours (h) minutes (min). For example, 1y 4w 3d 5h 30m expires the API key after 1 year, 4 weeks, 3 days, 5 hours, and 30 minutes of activity.
When an API key expires, there are two ways a key can be renewed:
The user can re-submit a request for consumption.
You (the provider) can renew the API key by selecting the
Renew option. For procedures, see
Renewing an API Key.
This field is optional. The default value "Unlimited" denotes that the API key never expires.
5. Select the Require Approval checkbox if you want to initiate an approval workflow for generating and renewing the API key.
When a client requests for generating or renewing an API key that triggers an approval, CentraSite initiates an approval workflow and submits the client’s request to the designated group of approvers.
Approvers receive the approval request in the
Pending Approval Requests (
) in the API details page. Approvers whose user account includes a valid email address also receive an email message informing them that a request is awaiting their approval.
CentraSite does not execute the client’s requested operation until it obtains the necessary approvals. If an approver rejects the request, CentraSite notifies the requestor.
If you do not select the
Require Approval checkbox, the request is automatically approved and
CentraSite executes the client’s registration request.
6. If you select the Require Approval checkbox, complete the following fields:
Field | Description |
Approval is needed from | All | Requests must be approved by all users specified in Approver Group. (It does not matter in which order the approvals are issued.) A single rejection will cause the request to be rejected. |
Any | Default. Requests can be approved or rejected by any single user in Approver Group. Only one user from the set of authorized approvers is required to approve or reject the request. |
Approver Group | Specify the approver group. You can specify multiple approver groups. |
For more information on approval management, see
Working with Approval Workflows.
7. In the Key Generation Settings section, complete the following fields so that CentraSite will send emails consumers initially request API keys.
CentraSite automatically populates the default email settings (Subject, Template, Action) with the <API Key Settings> information from the centrasite.xml properties file.
Field | Description |
Subject | The text that will appear on the subject line of the email. |
Template | The template that will be used to generate the body of the email message. To specify an additional template, use the plus button to add additional rows. Important: | CentraSite sends notifications about a request status to the consumer requesting for an API key; only if the client has enabled the Email notifications option in his User Preferences page. |
|
Action | Specify the approval action. |
Value | Description |
Approved | Default. CentraSite sends an email message to the client when requests are approved. If you choose this option, you can use the predefined template APIKeyGenerationSuccess.html for approval notifications if you do not want to create an email template of your own. |
Approval Request | CentraSite sends an email message to the approver(s) when requests are submitted for approval. If you choose this option, you can use the predefined template PendingApprovalNotification.html for pending-approval notifications if you do not want to create an email template of your own. |
Rejected | CentraSite sends an email message to the client when requests are rejected. If you choose this option, you can use the predefined template RejectionNotification.html for rejection notifications if you do not want to create an email template of your own. |
8. In the Key Renewal Settings section, complete the following fields so that CentraSite will send emails when consumers request API key renewals.
CentraSite automatically populates the default email settings (Subject, Template, Action) with the <API Key Settings> information fetched from the centrasite.xml properties file.
Field | Description |
Subject | The text that will appear on the subject line of the email. |
Template | The template that will be used to generate the body of the email message. To specify an additional template, use the plus button to add additional rows. Important: | CentraSite sends notifications to the client only if the client has enabled the Email notifications option in his User Preferences page. |
|
Action | Specify the approval action. |
Value | Description |
Approved | Default. CentraSite sends an email message to the client when requests are approved. If you choose this option, you can use the predefined template APIKeyRenewalSuccess.html for approval notifications if you do not want to create an email template of your own. |
Approval Request | CentraSite sends an email message to the approver group(s) when requests are submitted for approval. If you choose this option, you can use the predefined template APIKeyRenewalPendingNotification.html for pending-approval notifications if you do not want to create an email template of your own. |
Rejected | CentraSite sends an email message to the client when requests are rejected. If you choose this option, you can use the predefined template RejectionNotification.html for rejection notifications if you do not want to create an email template of your own. |
9. In the Key Revocation Settings section, complete the following fields so that CentraSite will send emails when consumers request to have API keys revoked.
CentraSite automatically populates the default email settings (Subject, Template, Action) with the <API Key Settings> information fetched from the centrasite.xml properties file.
Field | Description |
Subject | The text that will appear on the subject line of the email. |
Template | The template that will be used to generate the body of the email message to the client. If you choose this option, you can use the predefined template APIKeyRevocationSuccess.html for success notifications if you do not want to create an email template of your own. Important: | CentraSite sends notifications to the client only if the consumer has enabled the Email notifications option in his User Preferences page. |
|
10. Click the Configure button.
CentraSite internally creates and activates an API Key Generation Policy specific to the API. When a client registers as a consumer, this policy will start the process of approving and generating the API key.
