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 and secrets. Those keys can be used as authentication tokens, or they can be used to obtain OAUth access tokens.

Apigee Edge automatically generates API keys on behalf of apps. It enables API providers to view, approve, and revoke API keys. By applying a policy of the type VerifyApiKey, you can enforce verification of API keys at runtime. This ensures that no app 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 been revoked
  • The API key presented is approved to consume an API product that includes the URI in the request

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

For working examples of API proxies configured to enforce API key validation, please refer to the Using the samples available on GitHub.

For instructions on configuring API key validation using the Management UI, refer to Secure calls to your API through API key validation .

For instructions on configuring API key validation locally, refer to API keys.

"API keys" are also referred to as "consumer keys" and "app keys". In OAuth, API keys are referred to as 'client id'. The names can be used interchangeably.

Samples

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

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="{variable_name}" />
</VerifyAPIKey>
For example, to extract the API key from a query parameter called apikey:
<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.apikey" />
</VerifyAPIKey>

If a client app is expected to present the API key as the value of an HTTP header named AppKey, then set this value to request.header.AppKey.

Apigee Edge automatically populates a set of variables, including all HTTP headers and query parameters on a request message. You do not need to explicitly set the variables with an ExtractVariables policy.

If the API key is presented as part of the request payload, use an ExtractVariables policy to populate the variable before the VerifyApiKey policy in enforced.

For a list of available request message variables, see Variables reference.

Configuring the VerifyAPIKey policy

Configure MessageValidation using the following elements.

Field Name Description
name The unique name of the Policy. Use this name to reference a Policy within a Step definition. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

ref

The variable where the API key can be found.

Policy-specific error codes

See OAuth error code reference.

Policy-specific variables

When a VerifyAPIKey policy is enforced, Apigee Edge 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}*: Any custom attribute derived from the API product profile
  • apiproduct.developer.quota.limit*
  • apiproduct.developer.quota.interval*
  • apiproduct.developer.quota.timeunit*

* 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 Using the Edge management API to Publish APIs.

The following variables are populated for the App, Developer, and (if relevant) Company associated with the API key.

If the verifyapikey.{policy_name}.app.appType is "Company", then company attributes are populated. If app.appType is "Developer", then developer attributes are populated.

App

Prefix: verifyapikey.{policy_name}.app

  • name
  • id
  • accessType
  • callbackUrl
  • status
  • apiproducts/li>
  • scopes
  • appFamily
  • appParentStatus
  • appType
  • appParentId
  • created_by
  • created_at
  • last_modified_at
  • last_modified_by
  • {custom_attributes}

Developer

Prefix: verifyapikey.{policy_name}.developer

  • id
  • userName
  • firstName
  • lastName
  • email
  • status
  • apps
  • created_by
  • created_at
  • last_modified_at
  • last_modified_by
  • {custom_attributes}
  • Company

Company

Prefix: verifyapikey.{policy_name}.company

  • name
  • displayName
  • id
  • apps
  • appOwnerStatus
  • created_by
  • created_at
  • last_modified_at
  • last_modified_by
  • {custom_attributes}

Analytics variables

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

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

Policy schema

Each policy type is defined by an XML schema (.xsd). For reference, policy schemas are available on GitHub.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)