The APIs represented in the CentraSite Business UI require that requests for consumption include a unique identifier for consumption. A unique identifier can do the following:
Identify who is making a request.
Authenticate and validate the client who is making a request.
Authorize whether the client making a request is allowed to make that request.
CentraSite supports two separate mechanisms to create a unique identifier for clients to use for consuming APIs: API keys and OAuth 2.0 tokens.
The API provider (owner of the API) enforces the type of authentication (API key or OAuth2 token) required for consuming an API. Based on the authentication enforced for the API, an API consumer will request the API key or the OAuth2 token in order to consume (call) that API.
This section describes:
Configuring the API Consumption Settings for API Key Authentication
Configuring the API Consumption Settings for OAuth2 Authentication
To configure the API consumption settings, 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.
Note:
Until you have the instance-level "Modify" permission on an API (at a minimum), you will not be able to see the action in the API details page.
The API Provider (and users who belong to a role with the permissions stated above) can enforce API key authentication by configuring the API’s detail page. Such users can configure the following characteristics about client requests for 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:
Register as a consumer for the API, as specified in Registering as Consumers for an API.
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.
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 Using Your API Keys for Consumption.
To configure the API Consumption Settings for API key authentication
In CentraSite Business UI, display the details page for the API whose key settings you want to configure. For procedures, see the section Viewing Details for an API.
On the API details page, click
.
In the API Consumption Settings dialog, select API Keys.
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: a) The user can re-submit a request for consumption, or b) 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.
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.
Or:
If you choose not to select the Require Approval
checkbox, the request is automatically approved, and CentraSite executes the client’s
registration request.
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 the section Working with Approval Workflows in the document Administering the CentraSite Business UI.
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. For information about using email templates, see the section Working with Email Notifications. To specify an additional template, use the plus button to add additional rows. Important: |
|
| 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. |
|
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. For information about using email templates, see the section Working with Email Notifications. To specify an additional template, use the plus button to add additional rows. Important: |
|
| 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. |
|
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. For information about using email templates, see the section Working with Email Notifications. 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: |
|
Click the 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.
The type of OAuth2 authorization grant that Mediator supports is "Client Credentials". Client credentials are used as an authorization grant when the client is requesting API to protected resources based on an authorization previously arranged with the authorization server. That is, the client application gains authorization when it successfully registers with CentraSite as a consumer.
The API provider (and users who belong to a role with the permissions stated above) can enforce OAuth 2.0 authentication by configuring the API’s detail page. Such users can configure the following characteristics about the approval process of granting OAuth2 client credentials:
Specify the approval requirements for client requests for client credentials.
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.
Clients that want to use the OAuth2 protocol to call APIs in CentraSite must:
Register as a consumer for the API, as specified in Registering as Consumers for an API.
When the client registration request is approved, the client receives client credentials (a client_id and client_secret).
Request an OAuth2 access token by passing the client credentials to the Mediator-hosted REST service mediator.oauth2.getOAuth2AccessToken. This service will provide an OAuth2 access token to the client. For more information about this service, see Fetching and Using Your OAuth2 Access Tokens for Consumption .
To call the API, the client must pass their OAuth access token in an HTTP request header.
An OAuth2 token is a unique token that a client uses to invoke APIs using the OAuth 2.0 protocol. The token contains an identifier that uniquely identifies the client. The use of a token establishes the client's identity, and is used for both the authentication and authorization.
To configure the API Consumption Settings for OAuth 2.0 authentication
In CentraSite Business UI, display the details page for the API whose OAuth 2.0 token settings you want to configure. For procedures, see the section Viewing Details for an API.
On the API details page, click
.
In the API Consumption Settings dialog, select OAuth2.
In the Refresh Token After field, type the period of time after which Mediator should refresh the token after it expires.
This field is optional. The default value "Unlimited" denotes that the token never expires.
Select the Require Approval checkbox if you want to initiate an approval workflow for generating the client credentials.
When a client request 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.
Or:
If you choose not to select the Require Approval
checkbox, the request is automatically approved, and CentraSite executes the client’s
registration request.
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 the section Working with Approval Workflows.
In the Key Generation Settings section, complete the following fields so that CentraSite will send emails when a client requests a token.
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. For information about using email templates, see the section Working with Email Notifications. To specify another template, use the plus button to add additional rows. Important: |
|
| Action | Specify the approval action. | |
|
Value
|
Description
|
|
Approved |
Default. CentraSite sends an email message to clients 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 group(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 clients 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. |
|
Click the button.
When a client registers as a consumer, an approval request is sent to the approvers you specified above.
