Enforce access control using VerifyAPIKey

Was this helpful?

RESTful services are often exposed over the open Internet for consumption by developers building apps. API providers need a mechanism to prevent unauthorized access to the API. One approach is to provision developers with API keys.

The API Platform automatically generates API keys on behalf of apps. It enables you to view, approve, and revoke API keys. By applying a policy of the type VerifyApiKey, you can enforce runtime API verification.

For instructions on setting up API key validation, see Secure APIs with API keys

Note: "API keys" are also referred to as "consumer keys" and "app keys". The names can be used interchangeably.

API keys are verified at runtime to ensure that:

  • The API key presented is valid and has not been revoked
  • The API key presented is approved to consume an API product that includes the requested URI

The only setting required for the VerifyAPIKey defines the expected location of the API key. Only one location is supported per policy instance.

The API key is extracted from the request message by reference to a Flow variable. For example:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey>ref="{variable_name}"</APIKey>
</VerifyAPIKey>

For example, to extract the API key from a query parameter called apikey:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.apikey" />
</VerifyAPIKey>

When a VerifyAPIKey policy is enforced, the API Platform populates a set of variables. These variables are available to policies or code executed later in the Flow, and are often used to perform custom processing based on attributes of the API key such as the app name, the API product used to authorize the key, or custom attributes of the API key.

The variable prefix is verifyapikey.{policy_name}.

The variables populated are:

  • client_id: The consumer key (aka API key or app key) supplied by the requesting app
  • client_secret: The consumer secret associated with the consumer key
  • redirection_uris: Any redirect URIs in the request
  • developer.app.name: The app name of the developer app making the request
  • developer.id: The developerID of the developer registered as the owner of the requesting app
  • failed: Set when API Key validation fails
  • {custom_attribute_name_of_app}: Any custom attribute derived from the app profile
  • {custom_attribute_name_of_appkey}: Any custom attributes derived from the app key profile
  • apiproduct.name*: The name of the API product used to validate the request
  • apiproduct.{custom_attribute_name_of_apiproduct}*: Any custom attribute derived from the API product profile

API product variables will be populated automatically if the API products are configured with valid environment, proxies and API resources (derived from the proxy.pathsuffix). Explicitly setting flow.resource.name variable is not required.

Where the API products are not configured with valid environments and API proxies, then flow.resource.name must explicitly be set to populate API product variables in the flow.

For instructions on setting up API products, refer to Provision API products, developers and apps.

Analytics variables:

The following variables are automatically populated in Analytics when a VerifyAPIKey policy is enforced. The variables and values can thereafter be used as dimensions to build Analytics reports to gain visibility into consumption patterns by developers and applications.

  • apiproduct.name:
  • developer.app.name:
  • client_id:
  • developer.id:

Example: API Key Validation policy

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GetOAuthV1Info enabled="true" continueOnError="false" async="false" name="Policy-1347578787672">
    <DisplayName>Validate API Key Policy</DisplayName>
    <AppKey ref="request.queryparam.apikey"></AppKey>
</GetOAuthV1Info>