Clients that need to call (consume) APIs must register with CentraSite as consumers of the API.
Clients can register as consumers of APIs as a:
User or user group with a valid CentraSite user account. For procedures, see Authorized Centrasite User Accessing API as Logged on User.
Guest user (with or without a valid CentraSite user account). For procedures, see Authorized CentraSite User Accessing API as Guestor Unauthorized User Accessing API as Guest.
Consumer application (which is represented as an Application asset). An Application asset defines precise consumer identifiers (for example, a list of user names in HTTP headers, a range of IP addresses, etc.). Thus Mediator can identify or authenticate the consumers that are requesting an API. For procedures, see Registering Application Assets as Consumers.
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 call (consume) that API.
Clients that want to use the API key to call (consume) an API in CentraSite must:
Register as a consumer for the 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 the HTTP request header or as a query string parameter. The use of this key establishes the client's identity and authentication.
For information about using API keys to consume APIs, see Using Your API Keys for Consumption.
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 access to protected resources based on an authorization previously arranged with the authorization server. That is, the client application gains authorization when it registers with CentraSite as a consumer.
Clients that want to use the OAuth 2.0 protocol to call (consume) APIs in CentraSite must:
Register as a consumer for the API.
When the client registration request is approved, the client receives client credentials (a client_id and client_secret).
Pass the client credentials to the Mediator-hosted REST service mediator.oauth2.getOAuth2AccessToken.
This service will provide an OAuth2 access token to the client. For 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 as an integral part of the 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.
This section covers the following topics:
Users can register themselves as consumers of specified APIs, using the Consume action. That is, users can request permission to access specified APIs in the registry. The owners of the APIs may approve or reject such requests. The Consume action applies only to proxy APIs.
Note:
To enable CentraSite to issue email messages, an administrator must first configure CentraSite's email server settings. For
procedures, see the section Configuring the Email Server in the document Basic Operations.
To register a user as a consumer for an API
In CentraSite Business UI, display the details page for the API that you want to consume. For procedures, see the section Viewing Details for an API Proxy.
On the API details page, click
(
). This opens the Consume API dialog.
Depending on the type of user account you have in CentraSite, you must complete one of the following procedures:
Authorized Centrasite User Accessing API as a Logged-On User
- OR -
Authorized CentraSite User Accessing API as a Guest
- OR -
You must at least have the instance-level View permission for the specified API. If your user account belongs to a role that has either the "Manage Assets", "Create Assets", "Modify Assets" or "View Assets" permission for an organization, you automatically have permission to register as consumer for all APIs in that particular organization.
Specify the or client credentials.
In the Consumer Name field, specify your CentraSite username.
Select the Email me checkbox in order to receive auto-generated workflow notifications, and then specify your email address.
Enter a reason to request the API for consumption.
If the API's policy governance rule includes one or more "Evalaute" actions, you will see the Consumer Identifier field. Enter your consumer identifier, by which the provider will recognize your messages at run time. For details, see Configuring the Consumer Identification Profile.
Click .
A request is sent to the designated approvers. Upon approval, a request for consumption of the selected API will be sent to the provider of the API, who will then generate the API key / OAuth2 client credentials.
Once approved, the API consumption request will be processed and a notification will be sent to you at the specified email address.
If an approval workflow is not defined for the API, the API key / OAuth2 credentials is generated immediately.
To get your generated API keys or OAuth access tokens for consumption, refer to the section Obtaining Your API Keys and Access Tokens for Consumption.
In the Login page, enter your username and password and click .
Specify the or client credentials.
In the Consumer Name field, specify your CentraSite username.
Select the Email me checkbox in order to receive auto-generated workflow notifications, and then specify your email address.
Enter a reason to request the API for consumption.
If the API's policy governance rule includes one or more "Evalaute" actions, you will see the Consumer Identifier field. Enter your consumer identifier, by which the provider will recognize your messages at run time. For details, see Configuring the Consumer Identification Profile.
Click .
A request is sent to the designated approvers. Upon approval, a request for consumption of the selected API will be sent to the provider of the API, who will then generate the API key / OAuth2 credentials.
Once approved, the API consumption request will be processed and a notification will be sent to you at the specified email address.
If an approval workflow is not defined for the API, the API key / OAuth2 credentials is generated.
To get your generated API keys or OAuth access tokens for consumption, refer to the section Obtaining Your API Keys and Access Tokens for Consumption.
If you are a guest user without a valid CentraSite user account, CentraSite internally executes a consumer onboarding workflow. This workflow helps you to onboard in an organization of interest within the CentraSite registry/repository. An onboarding request is sent to the organization’s administrator for approval. On successful onboarding of the user, a request for consumption of the selected API will be sent to the provider of the API who will generate the API key or OAuth2 client credentials.
In the Request an Account page, specify the following:
Enter your First Name and Last Name.
Type in your password in the Password field.
Retype the password in the Confirm Password field.
Enter the Email address which you will use as username when signing into CentraSite Business UI.
Enter the Organization you want to join.
If the Organization field is left blank, CentraSite will automatically register the user as a consumer in the organization that was configured in the Global Onboarding Policy.
Click .
Specify the or client credentials.
In the Consumer Name field, specify your CentraSite user name.
Select the Email me checkbox in order to receive auto-generated workflow notifications, and then specify your email address.
Enter a reason to request the API for consumption.
If the API's policy governance rule includes one or more "Evalaute" actions, you will see the Consumer Identifier field. Enter your consumer identifier, by which the provider will recognize your messages at run time. For details, see Configuring the Consumer Identification Profile.
Click the button.
A consumer registration request is sent to the organization’s administrator for approval. Upon successful registration of the consumer, a request for consumption of the selected API will be sent to the provider of the API, who will then generate the API key / OAuth2 credentials.
If an approval workflow is not defined for the API, the API key / OAuth2 credentials is generated immediately.
To get your generated API keys or OAuth access tokens for consumption, refer to the section Obtaining Your API Keys and Access Tokens for Consumption.
If you have permissions to view an API, and you belong to a role that includes the "Register as Consumer" permission, the Consume action is enabled in the API details page. This action opens a dialog that lets you request the right to be a consumer of the specified API. You can request the right for any consumer application owned by any organization.
The request must be subsequently approved or rejected by the owner of the API.
To register an application asset as a consumer for an API
Display the details page for the API you want to consume. If you need procedures for this step, see the section Viewing Details for an API Proxy.
On the API's actions menu, click the
icon. This opens the Consume
API dialog.
In the Application textbox, type the keyword(s) to search for. CentraSite applies the filter to the application asset's name. Choose an application asset from the selection list.
If you want to specify additional application assets, use the plus button beside the Application field to create a new Application input field, and choose another application asset.
When you have specified all required applications, click . Requests to register the applications are sent to the owner of the specified API.
The owner of an API can either accept or decline a "Register as Consumer" request as follows:
Go to the API details page.
You will see the pending consumer registration requests
(
)
for an API in the description area of the Basic
Information profile, for example, "N consumer
registration requests are pending”.
If there are no pending consumer registration requests for the
API, this is displayed as “0".
Click the hyperlinked number (“N”)
to open the Pending Consumer Registration Requests dialog.
This dialog contains a list of all consumer registration requests that have
been submitted for the particular API, including requests that were
auto-approved.
Choose the consumer registration request that you want to review and approve by clicking its hyperlinked name.
The details for the request will appear in the Consumer Registration Request dialog.
In the Comment text box, type a comment (e.g., "Request rejected. Add required specifications to this API and resubmit".).
Click the or button to approve or reject the request.
After the applications are approved to consume the specified API, CentraSite automatically changes the consumer count in the API's Basic Information profile.
For details, see the section Monitoring Consumer Count for an Asset.
To view a summary of all "Register as Consumer" requests, go to the API details page:
If you are the owner of an API, and another user has made a request to register as a consumer of the API, you can view the request here. As the API owner, you can accept or decline the request.
If you have made a request to register as a consumer of an API owned by another user, you can view the status of the request here.
Note:
If an API has a pending state change approval request
and a pending consumer registration request, then the pending state change
approval takes priority over the pending consumer registration request.
CentraSite Business UI has extensive support for consumer-provider tracking that allows you to monitor the number of consumers for an API.
The number of users who consume an API is displayed in brackets with icons (representing the Consumers) in the description area of the Basic Information profile in the API details page, for example, "(5) Consumers". If no consumers are registered for the API, this is displayed as "(0) Consumers".
Clicking on this consumer count displays the consumers' information.
