VerifyAPIKey policy

You're viewing Apigee Edge documentation.
View Apigee X documentation.

What

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

Samples

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

curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey" />
</VerifyAPIKey>

curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="requestAPIKey.key"/>
</VerifyAPIKey>

<ExtractVariables async="false" continueOnError="false" enabled="true" name="SetAPIKeyVar">
    <Source>request</Source>
    <QueryParam name="myKey">
        <Pattern ignoreCase="true">{key}</Pattern>
    </QueryParam>
    <VariablePrefix>requestAPIKey</VariablePrefix>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

<AssignMessage async="false" continueOnError="false" enabled="true" name="accessverifyvars">
    <AssignVariable>
        <Name>devFirstName</Name>
        <Ref>verifyapikey.verify-api-key.developer.firstName</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <AssignVariable>
        <Name>devLastName</Name>
        <Ref>verifyapikey.verify-api-key.developer.lastName</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <AssignVariable>
        <Name>devEmail</Name>
        <Ref>verifyapikey.verify-api-key.developer.email</Ref>
        <Value>ErrorOnCopy</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

verifyapikey.{policy_name}

About the Verify API Key policy

When a developer registers an app on Edge, Edge automatically generates a consumer key and secret pair. You can see the app's consumer key and secret pair in the Edge UI or access them from the Edge API.

At the time of app registration, the developer selects one or more API products to associate with the app, where an API product is a collection of resources accessible through API proxies. The developer then passes the API key (consumer key) as part of every request to an API in an API product associated with the app. See Publishing overview for more.

API keys can be used as authentication tokens, or they can be used to obtain OAuth access tokens. In OAuth, API keys are referred to as "client id". The names can be used interchangeably. See OAuth home for more.

Edge automatically populates a set of flow variables when executing the Verify API Key policy. See Flow variables below for more.

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>

<VerifyAPIKey> attributes

The following example shows the attributes on the <VerifyAPIKey> tag:

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">

The following table describes attributes that are common to all policy parent elements:

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

<APIKey> element

This element specifies the flow variable that contains the API key. Typically, the client sends the API key in a query parameter, HTTP header or a form parameter. For example, if the key is sent in a header called x-apikey, the key will be found in the variable: request.header.x-apikey

Attributes

The following table describes the attributes of the <APIKey> element

Examples

In these examples, the key is passed in parameters and a header called x-apikey.

As a query parameter:

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

As an HTTP header:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey"/>
</VerifyAPIKey>

As an HTTP form parameter:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.formparam.x-apikey"/>
</VerifyAPIKey>

Schemas

Flow variables

When a Verify API Key policy is enforced on a valid API key, Edge populates a set of flow 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 policy populates several different types of flow variables, including:

• General
• App
• Developer
• Company
• Analytics

Each type of flow variable has a different prefix. All variables are scalars except those specifically indicated as arrays.

General flow variables

The following table lists the general flow variables populated by the Verify API Key policy. These variables are all prefixed by:

verifyapikey.{policy_name}

For example: verifyapikey.{policy_name}.client_id

The available variables include:

App flow variables

The following flow variables containing information about the app are populated by the policy. These variables are all prefixed by:

verifyapikey.{policy_name}.app.

For example:

verifyapikey.{policy_name}.app.name

The available variables include:

Developer flow variables

The following flow variables containing information about the developer are populated by the policy. These variables are all prefixed by:

verifyapikey.{policy_name}.developer

For example:

verifyapikey.{policy_name}.developer.id

The available variables include:

Company flow variables

The following flow variables containing information about the company are populated by the policy. These variables are all prefixed by:

verifyapikey.{policy_name}.company

For example:

verifyapikey.{policy_name}.company.name

The available variables include:

Analytics variables

The following variables are automatically populated in Analytics when a Verify API Key policy is enforced for a valid API key. These variables are only populated by the Verify API Key policy and the OAuth policies.

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 reference

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error responses

{  
   "fault":{  
      "faultstring":"Invalid ApiKey",
      "detail":{  
         "errorcode":"oauth.v2.InvalidApiKey"
      }
   }
}

{  
   "fault":{  
      "detail":{  
         "errorcode":"keymanagement.service.DeveloperStatusNotActive"
      },
      "faultstring":"Developer Status is not Active"
   }
}

Example fault rule

<FaultRule name="FailedToResolveAPIKey">
    <Step>
        <Name>AM-FailedToResolveAPIKey</Name>
    </Step>
    <Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition>
</FaultRule>

Related topics