Fetching and Using API Access Keys for Consumption
APIs are often exposed over the open internet for consumption. API Providers use API access keys as authentication tokens to prevent unauthorized access to an API.
CentraSite automatically generates the API keys when consumers request for consumption of the secured APIs. The API Providers can view, approve, and set expiration for the generated API keys. This ensures that no consumer can access a protected API without a valid key.
API access keys are verified at run-time to ensure that:
The access key presented is valid and has not expired.
The access key passed as a parameter in the URI or the HTTP/SOAP request for an API is approved to consume the API.
If an API is configured for the API key authentication, and you have successfully registered as a consumer for that particular API, then you would receive your API access key details through an email message.
Using the Generated API Key
CentraSite allows you to set API keys as part of the HTTP header for a REST API, the SOAP header for a SOAP API, or as the query component of a request URI.
Important:
In the case where a consumer is sending a request with both credentials (HTTP/SOAP header) and (query string), the HTTP/SOAP header takes precedence over the query string when the API Gateway is determining which credentials it should use for the consumption.
Request Header
The API keys are passed as the HTTP/SOAP header component of an API consumption request. The HTTP/SOAP header corresponds to an array of header names to include for that particular API consumption.
The following example demonstrates a typical HTTP/SOAP request with API keys that form the header value of the API Access URL:
x-CentraSite-APIKey:a4b5d569-2450-11e3-b3fc-b5a70ab4288a
Query String
Note:
Query string is only applicable for REST APIs.
The API keys are passed as the query component of a REST 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 a REST API for consumption using the Access URL and the generated API key, CentraSite automatically validates the API's 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 the API.
Example:
If a REST API consumption encounters a problem due to one or more of the following reasons, a 500 status code 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.