Verify API Key policy

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

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.

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. 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 flow variable where the API key can be found. The API key value can be sent as a query parameter, HTTP header, or form parameter.

For example request.queryparam.apiKey indicates that the API key will be present as a query parameter, as, for example, ?apiKey=1234567. To require the API key in an HTTP header, for example, set this value to request.header.apiKey. For form parameters, use request.formparam.apiKey.

Attributes

Attribute

Description

Default

Presence

ref

A reference to the variable in the request that contains the API key, as explained above. 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.

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.

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

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.