This page applies to Apigee and Apigee hybrid.
View
Apigee Edge documentation.
When a developer registers an app on Apigee, Apigee automatically generates a consumer key and secret pair. You can see the app's consumer key and secret pair in the Apigee UI or access them from the Apigee 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 information.
The VerifyAPIKey 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.
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.
Apigee automatically populates a set of flow variables when executing the Verify API Key policy. See Flow variables below for more.
This policy is an Extensible policy and use of this policy might have cost or utilization implications, depending on your Apigee license. For information on policy types and usage implications, see Policy types.
For a tutorial showing how to build an API proxy that uses the Verify API Key policy, see Secure an API by requiring API keys.
Samples
Key in query param
<VerifyAPIKey name="APIKeyVerifier">
<APIKey ref="request.queryparam.apikey" />
</VerifyAPIKey>In this example, the policy expects to find the API key in a flow variable called
request.queryparam.apikey. The variable request.queryparam.{name}
is a standard Apigee flow variable that is populated with the value of a query param passed
in the client request.
The following curl command passes the API key in a query param:
curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls
Key in header
<VerifyAPIKey name="APIKeyVerifier">
<APIKey ref="request.header.x-apikey" />
</VerifyAPIKey>In this example, the policy expects to find the API key in a flow variable called
request.header.x-apikey. The variable request.header.{name}
is a standard Apigee flow variable that is populated with the value of a header passed
in the client request.
The following cURL shows how to pass the API key in a header:
curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"
Key in variable
<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>Access policy flow variables
<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>
Apigee 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.
Learn Apigee
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"/> <CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Default value</CacheExpiryInSeconds/> </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:
| Attribute | Description | Default | Presence |
|---|---|---|---|
name |
The internal name of the policy. The value of the Optionally, use the |
N/A | Required |
continueOnError |
Set to Set to |
false | Optional |
enabled |
Set to Set to |
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 value of the policy's |
|---|---|
| Presence | Optional |
| Type | String |
<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
| Default | NA |
|---|---|
| Presence | Required |
| Type | String |
Attributes
The following table describes the attributes of the <APIKey> element
| 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 |
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><CacheExpiryInSeconds> element
This element enforces TTL on the cache, which enables customization of the time period for cached API key expiration. You can provide a flow variable and a default variable. If provided, the flow variable value takes precedence over the specified default value.
<CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Value 1</CacheExpiryInSeconds>
| Default | N/A
If you omit this element, the default expiration period for the cached API key is 180 seconds. |
|---|---|
| Presence | Optional |
| Type | Integer |
| Valid values | An integer from 1 to 180, inclusive. Specifies the expiration time in seconds. |
Attributes
The following table describes the attributes of the <CacheExpiryInSeconds> element
| Attribute | Description | Default | Presence |
|---|---|---|---|
| ref |
A reference to the flow variable containing the value for the cache expiration, expressed in seconds. If provided, the flow variable value takes precedence over the specified default value. |
N/A | Optional |
Schemas
Flow variables
When a Verify API Key policy is enforced on a valid API key, Apigee 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
- Analytics
- Monetization
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 or AppGroup app making the request. |
developer.app.name |
The app name of the developer or AppGroup app making the request. |
developer.id |
The ID of the developer or AppGroup registered as the owner of the requesting app. |
developer.{custom_attrib_name} |
Any custom attributes derived from the app key profile. |
DisplayName |
The value of the policy's <DisplayName> attribute. |
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
Managing API products. |
|
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. |
DisplayName |
The app's display name. |
status |
The app status, such as 'approved' or 'revoked'. |
apiproducts |
An array containing the list of 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 "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. |
AppGroup flow variables
The following flow variables containing information about the
AppGroups
are populated by the policy. These AppGroup attributes populate only if
verifyapikey.{policy_name}.app.appType is "AppGroup".
These variables are all prefixed by:
verifyapikey.{policy_name}.appgroup.
For example:
verifyapikey.{policy_name}.appgroup.name
The available variables include:
| Variable | Description |
|---|---|
name |
The name of the AppGroup. |
id |
The AppGroup ID. |
displayName |
The AppGroup display name. |
appOwnerStatus |
The status of the app owner: 'active', 'inactive', or 'login_lock'. |
created_at |
The date/time stamp when the AppGroup was created. |
created_by |
The email address of the developer who created the AppGroup. |
last_modified_at |
The date/time stamp when the AppGroup was last modified. |
last_modified_by |
The email address of the developer who last modified the AppGroup. |
{appgroup_custom_attributes} |
Any custom AppGroup 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}.developerFor 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. |
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.namedeveloper.app.nameclient_iddeveloper.id
Monetization flow variables
After authenticating the user, the VerifyAPIKey policy checks all published rate plans to determine which, if any, is active based on their activation and expiration times. If an active published rate plan is found, the following flow variables are populated:
| Variable | Description |
|---|---|
mint.mintng_is_apiproduct_monetized |
true if active published rate plan is found. |
mint.mintng_rate_plan_id |
Rate plan ID. |
mint.rateplan_end_time_ms |
Expiration time for the rate plan. For example: 1619433556408 |
mint.rateplan_start_time_ms |
Activation time of the rate plan. For example: 1618433956209 |
Error reference
本部分介绍当此政策触发错误时返回的故障代码和错误消息,以及由 Apigee 设置的故障变量。在开发故障规则以处理故障时,请务必了解此信息。如需了解详情,请参阅您需要了解的有关政策错误的信息和处理故障。
运行时错误
政策执行时可能会发生这些错误。
| 故障代码 | HTTP 状态 | 原因 |
|---|---|---|
keymanagement.service.consumer_key_missing_api_product_association |
400 |
应用凭据缺少 API 产品关联。请将密钥的应用与 API 产品相关联。请注意,这适用于所有应用类型,例如开发者应用和 AppGroup 应用。 |
keymanagement.service.DeveloperStatusNotActive |
401 |
创建具有您所用 API 密钥的开发者应用的开发者具有无效状态。将应用开发者的状态设置为无效时,将停用该开发者创建的所有开发者应用。具有适当权限的管理员用户(例如组织管理员)可以通过以下方式更改开发者的状态: |
keymanagement.service.invalid_client-app_not_approved |
401 |
与 API 密钥关联的开发者应用已被撤消。撤消的应用无法访问任何 API 产品,也无法调用由 Apigee 管理的任何 API。组织管理员可以使用 Apigee API 更改开发者应用的状态。请参阅生成密钥对或更新开发者应用状态。 |
oauth.v2.FailedToResolveAPIKey |
401 |
该政策要求在政策的 <APIKey> 元素中指定的变量中找到 API 密钥。 当预期变量不存在(无法解析)时,会发生此错误。 |
oauth.v2.InvalidApiKey |
401 |
Apigee 已收到 API 密钥,但该密钥无效。当 Apigee 在其数据库中查找密钥时,它必须与请求中发送的密钥完全匹配。如果 API 之前有效,请确保未重新生成密钥。如果重新生成密钥,且您尝试使用旧密钥,则会看到此错误。如需了解详情,请参阅通过注册应用来控制对 API 的访问权限。 |
oauth.v2.InvalidApiKeyForGivenResource |
401 |
Apigee 已收到 API 密钥,且该密钥有效;但是,它与通过产品与 API 代理关联的开发者应用中的已批准密钥不匹配。 |
部署错误
在您部署包含此政策的代理时,可能会发生这些错误。
| 错误名称 | 原因 |
|---|---|
SpecifyValueOrRefApiKey |
<APIKey> 元素未指定值或密钥。 |
故障变量
发生运行时错误时,系统会设置这些变量。如需了解详情,请参阅您需要了解的有关政策错误的信息。
| 变量 | 其中 | 示例 |
|---|---|---|
fault.name="fault_name" |
fault_name 是故障名称,如上面的运行时错误表中所列。故障名称是故障代码的最后一部分。 | fault.name Matches "FailedToResolveAPIKey" |
oauthV2.policy_name.failed |
policy_name 是抛出故障的政策的用户指定名称。 | oauthV2.VK-VerifyAPIKey.failed = true |
错误响应示例
{
"fault":{
"faultstring":"Invalid ApiKey",
"detail":{
"errorcode":"oauth.v2.InvalidApiKey"
}
}
}{
"fault":{
"detail":{
"errorcode":"keymanagement.service.DeveloperStatusNotActive"
},
"faultstring":"Developer Status is not Active"
}
}故障规则示例
<FaultRule name="FailedToResolveAPIKey">
<Step>
<Name>AM-FailedToResolveAPIKey</Name>
</Step>
<Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition>
</FaultRule>