Send Docs Feedback

Verify API Key policy

 

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.

Where

In most cases, the Verify API Key policy is the first policy in the request PreFlow because no further API processing should occur if a key is invalid or missing.

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

Samples

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

The policy extracts the API key from the request message by referencing the flow variable specified by the ref attribute. In this example, the policy extracts the API key from a flow variable named request.queryparam.apikey, which is populated by a query param named apikey.

The following URL shows how you pass the API key for this example:

http://{org-name}-test.apigee.net/v1/weather/forecastrss?w=12797282&apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls

where {org-name} is the name of your Edge organization.

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.AppKey" />
</VerifyAPIKey>

In this example, you configure the policy to look for the API key in a header named AppKey. The client app must then pass the API key as the value of an HTTP header named AppKey.

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

The policy can reference any variable that contains the key. The policy in this example extracts the API key from a variable named requestAPIKey.key.

How that variable is populated is up to you. For example, you could use the Extract Variables policy to populate requestAPIKey.key from a query parameter named myKey, as shown below:

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

Edge automatically populates a set of flow variables when executing the Verify API Key policy for a valid API key. You can use these variables to access information such as the app name, app ID, and information about the developer or company who registered the app. In the example above, you use the Assign Message policy to access the developer's first name, last name, and email address after the Verify API Key executes.

These variables are all prefixed by:

verifyapikey.{policy_name}

In this example, the Verify API key policy name is "verify-api-key". Therefore, you reference the first name of the developer making the request by accessing the variable verifyapikey.verify-api-key.developer.firstName.


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.   

API keys go by many names. You may see them referred to as 'API keys', 'app keys', and 'consumer keys'. All of these names are synonymous.

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

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

The following attributes are common to all policy parent elements.

Attribute Description Default Presence
name

The internal 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-language name.

N/A Required
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies.

Set to true to have flow execution continue even after a policy fails.

false Optional
enabled

Set to true to enforce the policy.

Set to false to "turn off" the policy. The policy will not be enforced even if it remains attached to a flow.

true Optional
async

This attribute is deprecated.

false Deprecated

<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>
Default:

N/A

If you omit this element, the the value of the policy's name attribute is used.

Presence: Optional
Type: String

 

<APIKey> element

References the variable containing the API key. The key can be contained in any variable accessible by the policy.

For example, you can pass the API key a request as a query parameter, HTTP header, or form parameter. You then access the API key as a flow variable in the request message.

Setting ref to the flow variable request.queryparam.apikeyquery indicates that the API key is passed as a query parameter named apikeyquery

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

If the API key is passed in an HTTP header named apikeyheader, set ref to request.header.apikeyheader. If it is passed as a form parameter named apikeyform, set ref to request.formparam.apikeyform

Default NA
Presence Required
Type String

Attributes

Attribute Description Default Presence
ref

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

N/A Required

Schemas

See our Github repository samples for the most recent 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:

Variable Description
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.id The ID of the developer app making the request.
developer.app.name The app name of the developer app making the request.
developer.id The ID of the developer registered as the owner of the requesting app.
developer.{custom_attrib_name} Any custom attributes derived from the app key profile.
failed Set to "true" when API Key validation fails.
{custom_app_attrib} Any custom attribute derived from the app profile. Specify the name of the custom attribute.
apiproduct.name* The name of the API product used to validate the request.
apiproduct.{custom_attrib_name}* Any custom attribute derived from the API product profile.
apiproduct.developer.quota.limit* The quota limit set on the API product, if any.
apiproduct.developer.quota.interval* The quota interval set on the API product, if any.
apiproduct.developer.quota.timeunit* The quota time unit set on the API product, if any.
* API product variables are populated automatically if the API products are configured with valid environment, proxies, and resources (derived from the proxy.pathsuffix). For instructions on setting up API products, see Using the Edge management API to Publish APIs.

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:

Variable Description
name The name of the app.
id The ID of the app.
accessType Unused by Apigee.
callbackUrl The callback URL of the app. Typically used only for OAuth.
status The app status, such as 'approved' or 'revoked'.
apiproducts An array containing the list of API products associated with the app. 
scopes An array of OAuth scopes assigned to the API products associated with the app.
appFamily Any app family containing the app, or "default".
appParentStatus The status of the app's parent, such as 'active' or 'inactive'
appType The app type, as either "Company" or "Developer".
appParentId The ID of the parent app.
created_at The date/time stamp when the app was created.
created_by The email address of the developer who created the app.
last_modified_at The date/time stamp when the app was last updated.
last_modified_by The email address of the developer who last updated the app.
{app_custom_attributes} Any custom app attribute. Specify the name of the custom attribute.

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.

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

For example:

verifyapikey.{policy_name}.developer.id

The available variables include:

Variable Description
id Returns {org_name}@@@{developer_id}
userName The developer's user name.
firstName The developer's first name.
lastName The developer's last name. 
email The developer's email address.
status The developer's status, as active, inactive, or login_lock.
apps An array of apps associated with the developer.
created_at The date/time stamp when the developer was created.
created_by The email address of the user who created the developer. 
last_modified_at The date/time stamp when the developer was last modified.
last_modified_by The email address of the user who modified the developer. 
{developer_custom_attributes} Any custom developer attribute. Specify the name of the custom attribute.
Company The name of the company, if any, associated with the developer.

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.

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

For example:

verifyapikey.{policy_name}.company.name

The available variables include:

Variable Description
name The company name.
displayName The display name of the company. 
id The company ID.
apps An array containing the list of company apps. 
appOwnerStatus
The status of the app owner, as active, inactive, or login_lock.
created_at The date/time stamp when the company was created.
created_by The email address of the user who created the company. 
last_modified_at The date/time stamp when the company was last modified.
last_modified_by The email address of the user who last modified the company. 
{company_custom_attributes} Any custom company attribute. Specify the name of the custom attribute.

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 codes

The VerifyAPIKey policy returns the following error codes and error messages in error responses:

For guidance on handling errors, see Fault handling. See also this Apigee Community post that illustrates a FaultRule pattern you can use to test for API key errors. 

ApiKeyNotApproved

Currently Edge does not report this error accurately. Instead, if a key is not approved (its status is set to "revoked" or "pending"), you will get the FailedToResolveAPIKey error instead. For more information and a possible workaround, see this post on the Apigee Community

CompanyStatusNotActive

This error arises when the Company associated with the Developer App that has the API key you are using has an inactive status. When a Company's status is set to inactive,  you cannot access the developers or apps associated with that Company.

Error message

Company Status is not Active.

Status

401 Unauthorized

JSON

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

Resolution

An org admin can change a Company's status using the management API. See Set the Status of a Company.

DeveloperStatusNotActive

This error arises when the developer who created the the Developer App that has the API key you are using has an inactive status. When an App Developer's status is set to inactive,  any Developer Apps created by that developer are deactivated.

Error message

Developer Status is not Active.

Status

401 Unauthorized

JSON

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

Resolution

An org admin can change a developer's status using the management API. See Set Developer Status.

 

FailedToResolveAPIKey

The VerifyAPIKey policy expects to find the API key in a variable that is specified in the policy's <APIKey> element. This error arises when the expected variable does not exist (cannot be resolved).

Error message

Failed to resolve API Key variable <variable name>

Status

401 Unauthorized

JSON

{  
   "fault":{  
      "faultstring":"Failed to resolve API Key variable <variable name>",
      "detail":{  
         "errorcode":"steps.oauth.v2.FailedToResolveAPIKey"
      }
   }
}

Resolution

Be sure the expected variable is being set. For example, if the <APIKey> element specifies the variable request.queryparam.apikey, then be sure your app is passing a query parameter called apikey. The parameter is case sensitive.

InvalidApiKey

An API key was received by Edge, but it is invalid. When Edge looks up the key in its database, it must exactly match the on that was sent in the request.

Error message

Invalid APIKey

Status

401 Unauthorized

JSON

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

Resolution

Verify that you are passing a valid key (Consumer Key) from a Developer App that includes a Product associated with your API proxy. If the API worked previously, make sure the key was not regenerated. If the key was regenerated, you will see this error if you try to use the old key. For details, see Register apps.

InvalidApiKeyForGivenResource

An API key was received by Edge, and it is valid; however, it does not match an approved key in the Developer App associated with your API proxy through a Product.

Possible causes include:

  • The API key was revoked or is pending approval. An administrator can revoke API keys through the Edge UI or with a management API. Note: This cause is reported inaccurately, and it should throw an APIKeyNotApproved error instead. See APIKeyNotApproved for more information.
  • The API key you are using is not associated with a Developer App that includes a Product associated with your API proxy.
  • The API key you are using is associated with a Developer App that includes a Product associated with your API proxy; however, the specific resource your API is requesting is not included in the Product.

Error message

Invalid ApiKey for given resource

Status

401 Unauthorized

JSON

{  
   "fault":{  
      "faultstring":"Invalid ApiKey for given resource",
      "detail":{  
         "errorcode":"oauth.v2.InvalidApiKeyForGivenResource"
      }
   }
}

Resolution

You need to check the Developer App from which you obtained your API key. Check that the app has a Product that includes your API proxy and the specific resource you are calling. Resources can be added explicitly or with wild-cards. It's very important to understand how resources are specified in Products, especially when using wild-cards. See Configuring the behavior of a resource path. See also Register apps.

invalid_client-app_not_approved

This error occurs when the Developer App associated with the API key is revoked.  A revoked app cannot access any API products and cannot invoke any API managed by Apigee Edge.

Error message

App not Approved

Status

401 Unauthorized

JSON

{
  "fault": {
    "faultstring": "App not Approved",
    "detail": {
      "errorcode": "keymanagement.service.invalid_client-app_not_approved"
    }
  }
}

Resolution

An org admin can change the status of a Developer App using the management API. See Approve or Revoke Developer App.

Related topics

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

 

Help or comments?