The following section describes how to fetch your API keys and access tokens that enable you to consume 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.
If you will be the using the API key authentication and you have successfully registered as a consumer for an API, you should have received your API key details.
The CentraSite Business user interface enables users to view details of an API key in the following ways:
Through the email notification messages that were auto-generated by CentraSite. For procedures, see the section Using the Email Notifications.
Through the Consumer Overview profile of an API. For procedures, see the section Using the API Details Page.
Through the User Preferences page for a consumer. For procedures, see the section Using the User Preferences
Once your API registration request is approved, CentraSite sends an automated email message containing details of the API key value and its usage to both the approver and consumer.
If you want to receive email messages of the API key, make sure:
You have the notification option set as in the User Preferences page.
You have specified a valid email address.
Access your mailbox.
The information contained in the email message depends on whether you access the API as a consumer or the owner.
If you were the requestor for the API registration, you will see the following information:
API key
Key expiration date
API key usage
If you are the owner of the API, you will see the following information:
API key
Key expiration date
You can use the following procedure to view the details of an API key via the API Details page.
To view the details of an API key
In CentraSite Business UI, display the details page of the API whose key value want to view. For procedure, see the section Viewing Details for an API Proxy.
In the API Details page, go to profile.
The information contained in this profile depends on whether you access the API as a consumer or the owner.
If you were the requestor for API registration, you will see the following information:
API key
Key expiration date
API key usage
If you are the owner of the API, you will see the following information:
API key
Key expiration date
Alternatively, you can use the following procedure to view the details of all your API keys via the User Preferences page.
To view the details of an API key
In the CentraSite Business UI navigation bar, click the profile name.
The User Preferences page appears.
Display My Access Keys.
This shows a list of your API keys in CentraSite.
Note:
The My Access Keys panel IS NOT VISIBLE if at least one API key is not available in your CentraSite registry/repository.
Each entry in the API key list contains the following information:
API key
Key value
Key expiration date
Additionally, you can do the following operations on the API key:
Renew 
your API key, provided the key has a limited usage period, as
described in the section Renewing Your API
Key.
Revoke your API key temporarily from the CentraSite registry, as
described in the section Revoking Your API
Key.
Delete 
your API key permanently from the CentraSite registry, as
described in the section Deleting Your API
Key.
RESTful APIs are often exposed over the open Internet for consumption. API providers need a mechanism to prevent unauthorized access to the API. One approach is to provision consumers with API keys. Those keys can be used as authentication tokens.
CentraSite API Management Solutions automatically generates API keys when consumers request to consume APIs. The API providers can view, approve and set expiration for API keys. This ensures that no consumer can access a protected API without a valid key.
API keys are verified at runtime to ensure that:
The API key presented is valid and has not expired.
The API key presented is approved to consume an API that includes the URI in the request.
Note:
Throughout this section, the term "Virtual Alias" is also
referred to as "API" or simply "API". The
name can be used interchangeably.
This section provides information about consuming APIs that are published in the webMethods Mediator. If you are using a different kind of PEP, refer to its documentation for publishing procedures and information.
To enable a consumer to consume an API, the following events must occur:
The consumer sends a request to consume a specified API. The request must include the consumer's authentication credentials.
CentraSite generates the API key for consumption of the API (the specific key generation steps depend on the configuration settings defined by the Provider of that particular API). Later, CentraSite prepares the API for publishing and invokes the API Key Generation policy on the Mediator. The consumer will use this API key in order to consume this API.
The API Key Generation policy publishes the API in the Mediator.
If the publication is successful, the API Key Generation policy returns a success message, including data that is pertinent to the published API. (This includes the API key that is required for consuming this API). If the publishing is unsuccessful, the deployer service returns a failure message.
The consumer accesses the URL for API consumption, sends the API key as integral part of the HTTP request header or as a query string, and upon validation of the API key consumes the API.
If the consumption is successful, the consumer uses the API. If the consumption is unsuccessful for some reasons of authentication, a 500 fault is returned.
To determine the consumer from which an API consumption request was submitted, an API must have the policy governance rule defined with at least one Evaluate action. This action extracts a specified evaluator from an incoming request and locates the consumer defined by that identifier.
For example, if you configure the "Evaluate IP Address" action to evaluate consumers by IP address, Mediator extracts the IP address from a request's HTTP header and searches its list of consumers for the consumer that is defined by that IP address.
You can configure the Evaluate actions to evaluate consumers based on the following information in a request message.
| Evaluator | Description |
|---|---|
| IP Address | The IP address from which the request originated. |
| Host Name | The name of the host machine from which the request originated. |
| HTTP Authentication Token | The user ID submitted by the requestor when it was asked to provide basic HTTP credentials (username and password). |
| WS-Security Authentication Token | The WSS username token supplied in the header of the SOAP request that the consumer submitted to the API. |
| XPath | The custom authentication credentials (tokens, or username and password token combination) supplied in the HTTP request header that the consumer submitted to the API. |
| Consumer Certificate | The X.509 certificate supplied in the header of the SOAP request that the consumer submitted to the API. |
REST services rely on HTTP methods like GET, POST, PUT and DELETE to make request to an API provider, so the API keys are closely tied to these HTTP methods, where they are sent as part of these HTTP method requests.
CentraSite allows you to set API keys as part of the HTTP header or as the query component of an API request.
Important:
In the case where a consumer is sending a request with both
credentials (HTTP header) and (query string), the HTTP header take precedence
over the query string when the Mediator is determining which credentials it
should use for the
consumption.
The API keys are passed as the HTTP header component of an API consumption request. The HTTP header corresponds to an array of header names to include for that particular API consumption.
The following example demonstrates a typical HTTP request with API keys that form the header value of the API Access URL.
x-CentraSite-APIKey:a4b5d569-2450-11e3-b3fc-b5a70ab4288a
The API keys are passed as the query component of an API consumption request.
The following example demonstrates a typical HTTP GET request with API keys that form a query string of the API Access URL.
http://localhost:5555/ws/RestAPI?APIKey=a4b5d569-2450-11e3-b3fc-b5a70ab4288a
Notice that the API keys are added to the path after a “?”, and specified as key-value pair.
When you request an API for consumption using the Access URL and the generated API key, CentraSite automatically validates the APIs run-time actions to ensure that any "Evaluate" action that appears in the policy governance rule of an API is validated with the consumer requesting for that API.
If the API consumption encounters a problem due to one or more of the following reasons, a 500 SOAP fault is returned.
If the API key value in the HTTP header or the query string is authenticated as invalid.
The sample message looks like this:
The request is authenticated as invalid.
If the HTTP header is not present in the request.
The sample message looks like this:
A required header is missing in the request.
If the API key value in the HTTP header is expired.
The sample message looks like this:
The API key has expired.
If you will be using the OAuth 2.0 protocol and you have successfully registered as a consumer for an API, you should have received your OAuth2 client credentials (a client_id and client_secret).
Now you need to obtain an OAuth2 access token by passing your client credentials to the Mediator-hosted REST service mediator.oauth2.getOAuth2AccessToken. This service will provide an OAuth2 access token that you can subsequently include in your requests to call the API.
The service's input parameters are:
client_id
client_secret
scope (optional). The scope value is the name of the virtual service. If the scope value
is valid, Mediator obtains the access token. If no scope value is provided, Mediator
provides the access token to the scope in which the client is allowed, and adds the
scope to the response. To pass the scope, pass it in the request body.
There are three ways in which a client can provide the inputs for this service:
Provide inputs in the Basic authentication header (recommended).
The client can provide the client credentials (client_id and client_secret) in the Authorization header using the following form:
Authorization: Basic <base-64-encoded client_id:password, client_secret>
If you want to pass the scope, pass it in the request body.
Provide JSON inputs for the service.
The client can send a JSON request to the service in the following form:
{
"client_id" : "",
"client_secret": "",
"scope" : ""
}Note:
The client should contain the header Content-type:application/json in the
request.
Provide inputs in the request body
The OAuth2 specifications do not support sending the client credentials over the URL as URL-Encoded. However, you can send the client credentials in the request body using the following form:
client_id=<client_id>&client_secret=<client_secret>&scope=<scope>
Note:
The client should contain the header Content-type:application/x-www-formurlencoded
in the request.
Note:
If a client provides the client_id and client_secret in both the Authorization header
and the request body, the credentials given in the Authorization header are used.
For security reasons it is recommended to use HTTPS in your production environment. If you will be using HTTPS as the transport protocol over which the OAuth2 access tokens will be granted authorization, you must set the parameters pg.oauth2.isHTTPS and pg.oauth2.ports as described in the section Advanced Settings in the document Administering webMethods Mediator.
Following are sample responses that are returned to the client:
Sample XML response:
<Response xmlns="https://localhost/rest/pub.mediator.oauth2.getOAuth2AccessToken"> <access_token>db95b40095f31439a1cd8f411e64abe8</access_token> <expires_in>3600</expires_in> <token_type>Bearer</token_type> </Response>
Sample JSON response:
{
"access_token": "db95b40095f31439a1cd8f411e64abe8",
"token_type": "Bearer",
"expires_in": 3600
}