Verify API Key policy

About | Samples | Element reference | Usage notes | Flow variables | Error codes | Related topics

What

The Verify API Key policy lets you enforce verification of API keys at runtime, letting only approved apps access your API resources. This policy ensures that keys are valid, have not been revoked, and are approved to consume specific API resources contained in your API products.

When you add your API resources to API products (best practice), a unique key is generated for each registered developer app that uses those products. But API keys are meaningless unless you use this policy to verify them. Without this policy, your API is wide open.

Where

This policy can be attached in the following locations, but see the notes following the table for specific guidance.

ProxyEndpoint TargetEndpoint
    PreFlow Flow PostFlow PreFlow Flow PostFlow    
Request    
    Response
    PostFlow Flow PreFlow PostFlow Flow PreFlow    

In most cases, the API key is included in the request. Attach the policy in one of the following locations:

  • Request / ProxyEndpoint / PreFlow, Flow, or PostFlow

    PreFlow is ideal, because no further API processing should occur if a key is invalid or missing.

Samples

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

The API key is extracted from the request message by reference to a Flow variable. This example policy extracts the API key from a query parameter called apikey.

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 Verify API Key policy in enforced.

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


Element Reference

Following are elements and attributes you can configure on this policy.

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <APIKey ref="variable_containing_api_key" />
</VerifyAPIKey>

Schemas

See our Github repository samples for the most recent schemas.


<VerifyAPIKey> attributes

Following are attributes you can set on the parent element. Child element sections in this topic provide their own list of attributes.

Attribute Description Default Presence
async

Set to true to specify that the policy should be run in a thread pool different than the pool servicing the request/response flow. Default is false.

Note: This setting is only used for for internal optimization. Contact Apigee support at the Support Portal for more information.

false Optional
continueOnError

Most policies are expected to return an error when a failure occurs (for example, when a Quota is exceeded). By setting this attribute to true, Flow execution continues on failure.

false Optional
enabled Determines whether a policy is enforced or not. If set to false, a policy is 'turned off', and not enforced (even though the policy remains attached to a Flow). true Optional
name

The unique machine name of the policy. Characters you can use in the name are restricted to: A-Z0-9._\-$ %. However, the Edge management UI enforces additional restrictions, such as automatically removing characters that are not alphanumeric.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-lanaguage name.

N/A Required

<DisplayName>

A natural-language name that labels the policy in the management UI proxy editor. If omitted, the policy name attribute is used.

<DisplayName>Custom display name for UI</DisplayName>
Default Policy name attribute value.
Presence Optional
Type String

<VerifyAPIKey>/<APIKey> element

References the variable where the API key can be found.

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.apikey" />
</VerifyAPIKey>
Default NA
Presence Required
Type In the ref attribute, String for a variable containing the API key

Attributes

Attribute Description Default Presence
ref

A reference to the variable in the request that contains the API key. Only one location is allowed per policy.

N/A Required

Usage notes

API keys can also be used as authentication tokens, or they can be used to obtain OAUth access tokens. "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.


Flow 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, see 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.

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}
If the verifyapikey.{policy_name}.app.appType is "Company", then company attributes are populated. If app.appType is "Developer", then developer attributes are populated.

Analytics variables

The following variables are automatically populated in Analytics when a Verify API Key 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

Error codes

See OAuth error code reference. For guidance on handling errors, see Fault handling.


Related topics

For working samples of API proxies, see the Samples reference.

  • For instructions on configuring API key validation using the Management UI, see Part 1: Create a secure API .
  • For instructions on configuring API key validation locally, see API keys.

 

 

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?)