Send Docs Feedback

Part 1: Create a secure API

It's important to protect your API from unauthorized access. One way to do that is to validate API keys (also called "public keys", "consumer keys" or "app keys").

The tutorial Create your first API: Step-by-step shows how to create an API proxy to access the Yahoo Weather service. In this tutorial, you create a new version of that API proxy that adds the Verify API Key policy to the API proxy. The advantage of creating a new version of the API proxy is that Apigee Edge creates all of the policies necessary to enforce API keys for you.

If you already have an existing API proxy, you can add the Verify API Key policy at any time. See Verify API Key policy for more.

When an app makes a request to your API, the app must supply a valid key. At runtime, the Verify API Key policy checks that the supplied API key:

  • Is valid
  • Hasn't been revoked
  • Matches the API key for the API product that exposes the requested resources

If the key is valid, the request is allowed. If the key is invalid, the request results in an authorization failure.

For more information on API keys, see Secure APIs with API keys.

Prerequisites for this tutorial

While it is not required, this tutorial assumes that you have completed the first tutorial, where you create an API proxy to access the Yahoo Weather service. If you have not yet completed this first tutorial, see Create your first API: Step-by-step.

Step 1: Create an API proxy

Configure an API proxy for the Yahoo! Weather service. This repeats some of the same actions as in the tutorial Create your first API proxy. However, you'll also add security to your API proxy in this step.

  1. Login to
  2. In the API Platform UI, select the APIs tab.
  3. Click (+) API Proxy.
  4. In the Build a Proxy wizard, select Reverse proxy (most common).
  5. Click Next.
  6. Follow the Build a Proxy wizard and make the following selections. If you followed the first tutorial, these steps and settings will be familiar.
    Field Value Description
    Proxy Name weatherapikey The name displayed for your API.
    Proxy Base Path /v1/weatherapikey The base path that the API platform uses to construct the API proxy URL. Apps will call this URL to invoke your API.
    Existing API The URL that the API Platform invokes on behalf of apps that call your API through the API proxy URL. This is the URL for the Yahoo! Weather API.
    Description Yahoo weather proxy The description of the API.
    API Key selected Adds API key-based authentication to your API proxy. When this option is selected, the Impose Quota per Developer option becomes selectable.
    Impose Quota per Developer selected Adds a policy that limits the number of request messages that can be submitted to your API proxy by an individual app over an interval of time.
    Publish API Product cleared When you select the Secure with API Keys option, the Publish API Product option is automatically selected. For the purposes of this tutorial, be sure to clear this option.
    Add CORS headers cleared Enables CORS (cross-origin resource sharing) to allow a browser to make direct requests to another domain.
    Virtual Hosts
    default selected To learn about virtual hosts, see Virtual hosts.
    secure selected  
    Deploy Environments test To learn about virtual hosts, see Virtual hosts.
  7. Click Build and Deploy
    In response, you should see an acknowledgment that your new API proxy was successfully created and deployed in the 'test' environment.
  8. Click View the weatherapikey proxy in the editor to display the details page for the API proxy.

Learn more:

Step 2: Define a conditional flow

A conditional flow lets you add specific processing steps to the API proxy when the flow's condition is met. 

In this step, you define a conditional flow for the request URI "/forecastrss", called the Path, along with the HTTP verb, GET, used to access the API proxy. While you define the conditional flow in this step, you add the processing steps specific to the conditional flow later in the tutorial.

  1. In the main menu of the management UI, click APIs to display the API Proxies page. If the API Platform page is not open, click here
  2. Click weatherapikey in the API Proxies table.
  3. Click the Develop tab in the upper right of the API proxy page.
  4. Click the "+" sign to the right of default under Proxy Endpoints to add a new conditional flow.
  5. In the New Conditional Flow dialog box:
    1. Enter forecast for the Flow Name.
    2. Enter weather conditional flow for the Description.
    3. Select Path and Verb for the Condition Type.  
    4. Enter /forecastrss as the Path.
    5. Choose GET for the Verb.
    6. Leave the Optional Target URL area blank.
    7. Click Add.
  6. Click Save in the upper-left corner to save your changes to the API proxy. Your conditional flow is now added to the proxy.

Learn more:

Step 3: Examine the generated policies

Because you chose the Secure with API Keys and Impose Quota per Developer options when you created the API proxy, Edge automatically added the following policies to your proxy:

Name Policy Type Description
Verify API Key Verify API Key Verifies the API key for an API product, returns an error if it is invalid, and if it is valid, looks up the attributes from the API product.
Remove Query Param Assign Message Modifies request messages in the API proxy flow to prevent the API key from being sent to the backend URL.
Impose Quota Quota Enforces a limit on the number of API calls made by apps over an interval of time
  1. Open the API Proxy Editor by clicking the Develop button in the details page for the weatherapikey API proxy to open the API Proxy Editor.

  2. In the Navigator on the left side of the API Proxy Editor, select PreFlow under Proxy Endpoints > default to show the generated policies in the Policy Designer.

    For more information on Flows and Endpoints, see Understanding APIs and API proxies.
  3. Select each policy to examine its settings.

Examine the Verify API Key policy

The first policy to examine is the Verify API Key policy, named Verify API Key. Typically, you want API key validation to happen as soon as a request is received by your API proxy. The PreFlow is always the first flow to execute at an endpoint, and the ProxyEndpoint is the first endpoint in the request pipeline. Because the Verify API Key policy is the first policy in the PreFlow, the API key will be validated by the policy as soon as it's received by the API proxy.

Click the Verify API Key policy icon, and examine the XML for the policy in the Code view. You can also view the values for the policy's XML elements and attributes in the Property Inspector. The XML for the policy should look something like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="verify-api-key">
    <DisplayName>Verify API Key</DisplayName>
    <APIKey ref="request.queryparam.apikey"/>

Note the <APIKey> element, which identifies where the policy should check for the API key. In this example, the policy looks for the API key in a query parameter named 'apikey'.

API keys can be located in a query parameter, an HTTP header, or a form parameter. Apigee Edge provides a message variable for each type of location.

Request variable Where expected key location is provided
request.queryparam.{queryparam_name} query parameter
request.header.{header_name} header
request.formparam.{formparam_name} form parameter
Learn more:

Examine the Assign Message policy

The next policy in the PreFlow is an Assign Message policy named Remove Query Param apikey. The Assign Message policy defines a set of elements that perform actions such as populating or modifying HTTP headers, query parameters, and XML or JSON payload content.

Examine the XML for the Assign Message policy. The XML for the policy should look like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage async="false" continueOnError="false" enabled="true" name="remove-query-param-apikey">
    <DisplayName>Remove Query Param apikey</DisplayName>
            <QueryParam name="apikey"/>
    <AssignTo createNew="false" transport="http" type="request"/>

In this example, the policy uses a <Remove> element to remove the query parameter named apikey from the HTTP request message attached to the flow so it is not sent to the backend service. Only the Verify API Key policy needs to be aware of the API key.

Learn more:

Examine the Quota policy

The final policy in the PreFlow is a Quota policy named Impose Quota. This policy enforces a limit on the number of API calls made by apps over an interval of time. The limit can be set in the policy, or in the API product that contains this API proxy. For example, you may want to limit apps to 1 request per minute, or to 10,000 requests per month.

Examine the XML for the Quota. The XML for the policy should look like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Quota async="false" continueOnError="false" enabled="true" name="impose-quota">
    <DisplayName>Impose Quota</DisplayName>
    <Allow countRef="verifyapikey.verify-api-key.apiproduct.developer.quota.limit" count="2000"/>
    <Interval ref="verifyapikey.verify-api-key.apiproduct.developer.quota.interval">1</Interval>
    <TimeUnit ref="verifyapikey.verify-api-key.apiproduct.developer.quota.timeunit">month</TimeUnit>

The <Allow> element of the Quota policy sets values for the maximum count of messages for the quota (2000). The <Interval> and <TimeUnit> elements specify the time interval as 1 month. The policy also references variables that are populated by Edge when the VerifyAPIKey policy is enforced. These values take precedence over the values set in the policy. For example, the following specifies a maximum message count for the quota based on the limit set in the API product that is used in validating the request:

<Allow countRef="verifyapikey.verify-api-key.apiproduct.developer.quota.limit" count="5000"/>

Learn more:

Step 4: Request the Yahoo Weather API by using your Edge API proxy

Now that you have an API proxy for the Yahoo Weather API, you can make requests to it through Apigee Edge. The first thing you need to determine is the complete URL of the resource of the API proxy that you want to access. That URL has the form:


In your Web browser, enter the following, substituting your Apigee organization name for {org-name}:


For example:

Because this API proxy uses the VerifyAPIKey policy, which expects an API key to be passed in a query parameter named 'apikey' the request fails with the following message: 

{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

You now have to generate a valid key before you can make a request to this API.

To use a browser to make the request:

  1. Enter the URL in a browser window.

To use the Trace page to make the request:

  1. In management UI, click the APIs tab.
  2. Click weatherapikey in the API Proxies table.
  3. On the weatherapikey detail page, click the Trace button to access the Trace page.
  4. On the Trace page, choose the test environment.
  5. Click Start Trace Session.
  6. Enter the URL in the URL field.
  7. Click Send.

To use the Apigee Console to make the request:

  1. From the Trace page, click Send with the Apigee Console, just below the Send button in the Send Requests area of the Trace page.
    The console appears in another browser window.
  2. Enter the URL of your API.
  3. Click Send.

To use cURL to make the request:

  1. Install cURL.
    The cURL tool is a convenient way to submit URL-based commands from a command line.

  2. Use cURL to request the URL:

    curl ""

Step 5: Where to next?

Now that you have a secure API defined on Edge, define the API product, developer, and app required to generate the key necessary to make requests to the API.

Continue on to Part 2: Generate and test an API key to generate the API key.


Help or comments?