API keys provide a simple mechanism for authenticating apps. Apigee Edge generates API keys for apps, and enables you to add API key-based authentication to your APIs using policies. Using Apigee Edge, you can issue, administer and validate API keys without writing any code. This topic shows you how to add API key validation to an 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.

When apps are registered with Edge Developer Services, a consumer key and secret pair is generated for the app. Edge API Services stores the consumer key for future validation. The app developer embeds the consumer key in the client app. The client app must present the consumer key for each request. API Services validates the consumer key before permitting the app's request.

API key validation is the simplest form of app-based security that you can configure for an API. Apps simply present an API key, and Apigee Edge checks to see that the API key is in an approved state for the resource being requested. For this reason the security associated with API keys is limited. API keys can easily be extracted from app code and used to access an API. You may find that API keys work better as unique app identifiers than as security tokens.

A working sample API proxy that enforces API key validation is available in the API Platform Samples available on Github. You can use the sample API proxy to secure your own API. Locate the API proxy found under /sample-proxies/apikey. Modify the TargetEndpoint configuration to point to your URL. Then deploy.

Policy configuration

You can set up API key validation for an API by attaching a policy of type. The only required setting for a ValidateAPIKey policy is the expected location of the API key in the client request. The API proxy will check the location that you specify, and extract the API key. If the API key is not present in the expected location, then an error is thrown and the request is rejected. API keys can be located in a query parameter, a form parameter, or an HTTP header.

For example, the policy configuration below defines the expected key location as a query parameter named apikey. A successful request must present the API key as a query parameter appended to the request, for example,?apikey=Y7yeiuhcbKJHD790.

To validate API keys, create the following policy:

<VerifyAPIKey name="APIKeyValidation">
  <APIKey>request.queryparameter.apikey</APIKey>
</VerifyAPIKey>

This policy can be attached to any API that you need to protect.

Comprehensive documentation of this policy type can be found in the policy reference topic, Verify API Key policy.

API proxies automatically passthrough all HTTP headers and query parameters that are present on the request. Therefore, after the API key has been validated, it's a good idea to strip it from the message so that the API key is not sent over the wire to the backend service. You can do that using a policy of type AssignMessage as follows:

<AssignMessage name="StripApiKey">
    <DisplayName>Remove Query Param</DisplayName>
    <Remove>
        <QueryParams>
            <QueryParam name="apikey"/>
        </QueryParams>
    </Remove>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"></AssignTo>
</AssignMessage>

Policy attachment

The policies must be attached to an API proxy Flow as processing Steps. By applying the policy to the request PreFlow, API keys are verified on every request received by the API proxy from a client app. After verification, the API key is stripped from the outbound request.

Attach the policies to the ProxyEndpoint of the API proxy to be protected as follows:

<ProxyEndpoint name="default">
  <PreFlow>
    <Request>
      <Step><Name>ValidateAPIKey</Name></Step>
      <Step><Name>StripApiKey</Name></Step>
    </Request>
  </PreFlow>

After you attach the policy, deploy the API proxy.

Submitting a request with a valid API key

As an admin in your organization, you can retrieve any app's API key as follows:

$ curl https://api.enterprise.apigee.com/v1/o/{myorg}/developers/{developer_email}/apps/{app_name} -u myname:mypass 
Remember to substitute your organization for {myorg} and your username and password for myname:mypass.

The app profile that is returned for this call provides the consumer key (API key) and secret. The consumer key value is the value you use for the API key in your request to the protected API.

For example, a request that does not include an API key results in an authorization failure.

$ curl http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

The failure message indicates that the policy checked for an API key but did not find a valid key:

OAuth Failure : Could not resolve the app key with variable request.queryparam.apikey

When the consumer key for the app is included as a query parameter, the expected result is successful authorization:

$ curl http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282&"apikey=PulSCqMnXGchW0pC0s5o9ngHVTWMeLqk"

The expected result is a successful response from the weather service.

Modifying the value of the API key value in the request results in an authorization failure:

$ curl http://{org_name}-test.apigee.net/weather?forecastrss?w=12797282&"apikey=PulSCqMnXGchW0"

Results in:

OAuth Failure : Consumer Key is Invalid

Remember, as an admin for your organization, you can retrieve the consumer key for any app registered in an organization:

$ curl https://api.enterprise.apigee.com/v1/o/{myorg}/developers/{developer_email}/apps/{app_name} -u myname:mypass 

A tutorial that demonstrates step-by-step API key configuration is available. See Part 1: Create a secure API.

Get help

For help, see Apigee Customer Support.

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