Secure an API by requiring API keys

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

Note: This video was recorded with a previous version of the Apigee UI; however, the concepts are still valid.

Video: Check out this short video for an introduction on securing your API.

What you'll learn

This tutorial explains how to:

• Create an API proxy that requires an API key.
• Create an API product, a developer, and a developer app.
• Call your API with an API key.

It's important to protect your API from unauthorized access. One way to do that is with API keys.

When an app makes a request to an API proxy that is configured to verify an API key, 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.

Note: In order to complete this tutorial, you'll be creating and deploying a proxy that uses extensible policies vs. standard policies.

Create the API proxy

Apigee in Cloud console

1. In the Google Cloud console, go to the Proxy development > API proxies page.

   Go to API proxies

2. Select your organization from the project picker in the Google Cloud pane. The organization name is the same as your Google Cloud project name.
3. Click + Create.
4. In the Create a proxy pane, under Proxy template, select Reverse proxy (Most common). A reverse proxy routes incoming traffic to a backend service.
5. Configure the proxy as follows:
   

   Name	Value
   Proxy Name	helloworld_apikey
   Base Path	/helloapikey The Project Base Path is part of the URL used to make requests to the API proxy.
   Description	hello world protected by API key
   Target (Existing API)	http://mocktarget.apigee.net This defines the target URL that Apigee invokes on a request to the API proxy. This target just returns a simple response: Hello, Guest!.

6. Click Next.
7. Deploy (optional). Leave these fields blank.
8. Click Create.
9. Apigee creates the new proxy and displays the summary of the proxy details in the Proxy summary pane.

Classic UI

1. Go to the Apigee UI and sign in.
2. Select your organization using the drop-down menu in the upper left corner of the UI.

3. Click Develop > API Proxies to display the API proxies list.

4. Click Create New.
   
5. In the Build a Proxy wizard, select Reverse proxy (most common).
6. Configure the proxy as follows:
   

   In this field	do this
   Proxy Name	Enter: helloworld_apikey
   Project Base Path	Change to: /helloapikey The Project Base Path is part of the URL used to make requests to the API proxy.
   Description	Enter: hello world protected by API key
   Target (Existing API)	Enter: http://mocktarget.apigee.net This defines the target URL that Apigee invokes on a request to the API proxy. This target just returns a simple response: Hello, Guest!.

7. Click Next.
8. On the Common policies page, select API Key. This option automatically adds two policies to your API proxy and creates an API product needed for generating the API key.
9. Click Next.
10. On the Summary page, make sure a deployment environment is selected, and click Create and deploy.
11. Click Edit proxy to display the Overview page for the API proxy.

View the policies

Apigee in Cloud console

1. In the Proxy summary pane for the helloworld_apikey proxy, click the Develop tab.
2. In the Policies menu, click Add policy.
3. In the Create policy pane, under Security, select Verify API Key.
4. In the Verify API Key pane, complete the required fields in the Name and Display name sections using the following values:
   • Name: Enter a policy name. For example, VerifyAPIKey.
   • Display name: Enter policy name for use in the UI. For example, Verify API Key.
5. Click Create.
6. Click to add another policy.
7. In the Create policy pane, under Mediation, select Assign Message.
8. In the Assign Message pane, complete the required fields in the Name and Display name sections using the following values:
   • Name: Enter a policy name. For example, AssignMessage.
   • Display name: Enter policy name for use in the UI. For example, Assign Message.
9. Click Create.
10. The <APIKey> element in the XML code below specifies the location of the API key within the incoming request. By default, the policy retrieves the key from a query parameter named apikey in the HTTP request.

    <APIKey ref="request.queryparam.apikey" />

    The name apikey is arbitrary and can be any property that contains the API key.

11. Update the contents of the Assign Message policy to the following:
    Note: The policy name will change to Remove Query Param apikey once you make this edit.

<AssignMessage async="false" continueOnError="false" enabled="true" name="remove-query-param-apikey">
    <DisplayName>Remove Query Param apikey</DisplayName>
    <Remove>
        <QueryParams>
            <QueryParam name="apikey"/>
        </QueryParams>
    </Remove>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

12. Add the VerifyApiKey and Remove Query Param apikey policies.
    1. In the Proxy endpoints menu, click Preflow.
    2. In the Request pane of the visual editor, click Add policy step.
    3. In the Add policy step pane, select Verify API Key.
    4. Click Add.
    5. In the Request pane of the visual editor, click Add policy step.
    6. In the Add policy step pane, select Remove Query Param apikey.
    7. Click Add.
13. Click Save.
14. Deploy your proxy to an environment:
    1. Click Deploy.
    2. Select a Revision and an Environment.
    3. Click Deploy.
15. Test your changes by calling the API as described in Try to call the API.

Classic UI

1. In the API proxy editor, click the Develop tab. You'll see that two policies have been added to the request flow of the API proxy:
   • Verify API Key – Checks the API call to make sure a valid API key is present (sent as a query parameter).
   • Remove Query Param apikey – An Assign Message policy that removes the API key after it's checked, so that it doesn't get passed around and exposed unnecessarily.

2. Click the Verify API Key policy icon in the flow view, and look at the policy's XML configuration in the lower code view. The <APIKey> element tells the policy where it should look for the API key when the call is made. By default, it looks for the key as a query parameter called apikey in the HTTP request:

   <APIKey ref="request.queryparam.apikey" />

   The name apikey is arbitrary and can be any property that contains the API key.

Try to call the API

In this step, you'll make a successful API call directly to the target service, then you'll make an unsuccessful call to the API proxy to see how it's being protected by the policies.

1. Success

   In a web browser, go to the following address. This is the target service that the API proxy is configured to forward the request to, but you'll hit it directly for now:

   http://mocktarget.apigee.net

   You should get this successful response: Hello, Guest!

2. Failure

   Now try to call your API proxy:

   curl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey

   where YOUR ENV_GROUP_HOSTNAME is the environment group hostname. See Find the environment group hostname.

   Note: If you have trouble calling the proxy, you may need to add the Host header, as described in Deploy a sample proxy.

   Without the Verify API Key policy, this call would give you the same response as the previous call. But in this case, you should get the following error response:

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

   which means, correctly, that you didn't pass a valid API key (as a query parameter).

In the next steps, you'll get the required API key.

Adding an API product

Apigee in Cloud console

To add an API product using the Apigee UI:

1. In the Google Cloud console, go to the Distribution > API products page:

   Go to API products

2. Click +Create.
3. Enter the Product details for your API product.
   

   Field	Description
   Name	Internal name of the API product. Do not specify special characters in the name. Note: You cannot edit the name once the API product is created.
   Display name	Display name for the API product. The display name is used in the UI and you can edit it at any time. If not specified, the Name value is used. This field is auto-filled using the Name value; you can edit or delete its contents. The display name can include special characters.
   Description	Description of the API product.
   Environment	Environments to which the API product will allow access. For example, test or prod.
   Access	Select Public.
   Automatically approve access requests	Enable automatic approval of key requests for this API product from any app.
   Quota	Ignore for this tutorial.
   Allowed OAuth Scopes	Ignore for this tutorial.

4. In the Operations section, click Add an operation.
5. In the API Proxy field, select the API proxy you just created.
6. In the Path field, enter "/". Ignore the other fields.
7. Click Save to save the operation.
8. Click Save to save the API product.

For more information on adding an API product, see Create an API product.

Classic UI

To add an API product using the Apigee UI:

1. Select Publish > API Products.
2. Click +Create.
3. Enter the Product Details for your API product.
   

   Field	Description
   Name	Internal name of the API product. Do not specify special characters in the name. Note: You cannot edit the name once the API product is created.
   Display name	Display name for the API product. The display name is used in the UI and you can edit it at any time. If not specified, the Name value will be used. This field is auto-filled using the Name value; you can edit or delete its contents. The display name can include special characters.
   Description	Description of the API product.
   Environment	Environments to which the API product will allow access. For example, test or prod.
   Access	Select Public.
   Automatically approve access requests	Enable automatic approval of key requests for this API product from any app.
   Quota	Ignore for this tutorial.
   Allowed OAuth Scopes	Ignore for this tutorial.

4. In the Operations section, click ADD AN OPERATION.
5. In the API Proxy field, select the API proxy you just created.
6. In the Path field, enter "/". Ignore the other fields.
7. Click Save to save the Operation.
8. Click Save to save the API product.

Add a developer and app to your organization

Next, we're going to simulate the workflow of a developer signing up to use your APIs. A developer will have one or more apps that call your APIs, and each app gets a unique API key. This gives you, the API provider, more granular control over access to your APIs and more granular reporting on API traffic by app.

Create a developer

Apigee in Cloud console

To create a developer:

1. In the Google Cloud console, go to the Distribution > Developers page:

   Go to Developers

2. Click + Create.
3. Enter the following in the Add Developer window:
   

   Field	Value
   First Name	Keyser
   Last Name	Soze
   Email	[e-mail]
   Username	keyser

4. Click Add.

For more information on creating a developer, see Registering app developers.

Classic UI

To create a developer:

1. Select Publish > Developers in the menu.
   Note: If you are still in the Develop screen, click on the "<" by DEVELOP to display the menu and select Publish > Developers
2. Click + Developer.
3. Enter the following in the New Developer window:
   

   In this field	enter
   First Name	Keyser
   Last Name	Soze
   Username	keyser
   Email	[e-mail]

4. Click Create.

Register an app

Apigee in Cloud console

1. In the Google Cloud console, go to the Distribution > Apps page:

   Go to Apps

2. Click + Create.
3. Enter the following in the Create App window:
   

   Field	Value
   App Name	Enter: keyser_app
   Display Name	Enter: keyser_app
   Developer	Select: Keyser Soze ([e-mail])
   Callback URL	Leave blank
   Notes	Leave blank

4. In the Credentials section, click Add credential.
5. Select Never. The credentials for this app will never expire.
6. Click Add products.
7. Select the product you just created.
8. Click Add.
9. Click Create.

For more information on registering an app, see Registering an app.

Classic UI

To register a developer app:

1. Select Publish > Apps.
2. Click + App.
3. Enter the following in the New Developer App window:
   

   Field	Value
   Name and Display Name	Enter: keyser_app
   Developer	Select: Keyser Soze ([e-mail])
   Callback URL and Notes	Leave blank

4. In the Credentials section, select Never. The credentials for this app will never expire.
5. Click Add product.
6. Select the product you just created.
7. Click Create.

Get the API key

Apigee in Cloud console

To get the API key:

1. In the Google Cloud console, go to the Distribution > Apps page.

   Go to Apps

2. Select the required app from the list of apps.
3. On the View app page, under Credentials, click next to the Key field. Notice that the key is associated with the product you created.
4. Click Copy. You'll use this key in the next step.

Classic UI

To get the API key:

1. On the Apps page (Publish > Apps), click keyser_app.
2. On the keyser_app page, click Show next to Key in the Credentials section. Notice that the key is associated with the product you created.
   
3. Select and copy the key. You'll use it in the next step.

Call the API with a key

Now that you have an API key, you can use it to call the API proxy. Paste the API key as shown, as a query parameter. Make sure there are no extra spaces in the query parameter.

curl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey?apikey=YOUR_API_KEY

Now when you call the API proxy, you should get this response: Hello, Guest!

Congratulations! You've created an API proxy and protected it by requiring that a valid API key be included in the call.

Note that in general it's not good practice to pass an API key as a query parameter. You should consider passing it in the HTTP header instead.

Best practice: Passing the key in the HTTP header

Note: It's a good practice to pass the API key in a header rather than in a query parameter. Query parameters appear in the browser history and network logs, which could present a security risk. Headers do not appear in the browser history and network logs.

In this step, you will modify the proxy to look for the API key in a header called x-apikey.

Apigee in Cloud console

1. In the Google Cloud console, go to the Proxy development > API proxies page.

Go to API proxies

2. Select the required proxy from the list of proxies.
3. On the Proxy details page, click Develop.
4. Modify the policy XML to tell the policy to look in the header rather than in the queryparam:

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

5. Click Save to save the changes.
6. Click Deploy.
7. Select a Revision and an Environment.
8. Click Deploy.

9. Make the following API call using cURL to pass the API key as a header called x-apikey. Don't forget to substitute your organization name.

   curl -v -H "x-apikey: YOUR_API_KEY" http://YOUR_ENV_GROUP_HOSTNAME/helloapikey

Note that to fully complete the change, you'd also need to configure the Assign Message policy to remove the header instead of the query parameter. For example:

<Remove>
  <Headers>
      <Header name="x-apikey"/>
  </Headers>
</Remove>

Note: You could also pass the API key as a form parameter. If you did, the Verify API Key policy would be configured like this:

<APIKey ref="request.formparam.YOUR_API_KEY"/>

Classic UI

1. Edit the API proxy. Select Develop > API Proxies > helloworld_apikey, and go to the Develop view.

2. Select the Verify API Key policy, and modify the policy XML to tell the policy to look in the header rather than in the queryparam:

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

3. Save the API proxy and use Deploy to deploy it.

4. Make the following API call using cURL to pass the API key as a header called x-apikey. Don't forget to substitute your organization name.

   curl -v -H "x-apikey: {api_key_goes_here}" http://YOUR_ENV_GROUP_HOSTNAME/helloapikey

Note that to fully complete the change, you'd also need to configure the Assign Message policy to remove the header instead of the query parameter. For example:

<Remove>
  <Headers>
      <Header name="x-apikey"/>
  </Headers>
</Remove>

Note: You could also pass the API key as a form parameter. If you did, the Verify API Key policy would be configured like this:

<APIKey ref="request.formparam.YOUR_API_KEY"/>

Related topics

Here are some topics related to API products and keys:

• Managing API products
• API keys
• Registering app developers
• Register apps and manage API keys
• Verify API Key policy

API protection often involves additional security such as OAuth, an open protocol that exchanges credentials (like username and password) for access tokens. Access tokens are long, random strings that can be passed through a message pipeline, including from app to app, without compromising the original credentials.

For an overview of security-related topics, see Securing a proxy.

Send feedback