You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/tutorials/secure-calls-your-api-through-api-key-validation). info
**What you'll learn**

Through this tutorial, you'll learn to:

- Create an API proxy that requires an API key.
- Add an API product.
- Add a developer and register an 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 (also called *public keys*, *consumer keys* or *app keys*).

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.

In this tutorial, you'll create an API proxy that requires a valid API
key to access it.

## What you'll need

- An Apigee Edge account. If you don't have one yet, you can sign up with the directions at [Creating an Apigee Edge account](https://docs.apigee.com/api-platform/get-started/creating-apigee-edge-account).
- A web browser to make an API call.
- (For the extra credit section, not required) [cURL](https://curl.haxx.se/) installed on your machine to make API calls from the command line.

## Create the API proxy

**About the 'mocktarget'**

The **mocktarget** service is hosted at Apigee and returns simple
data. It requires no API key or access token. In fact, you can access it
in a web browser. Try it out by clicking the following:

[http://mocktarget.apigee.net](https://mocktarget.apigee.net)

The target returns `Hello, Guest!`. Use the
[/help](https://mocktarget.apigee.net/help)
resource to get a help page of other API resources that are available

1. Go to <https://apigee.com/edge> and sign in.
2. Switch to the organization you want by clicking your user name at the
   top of the side navigation bar to display the user profile menu, and then
   selecting the organization from the list.

   ![select org in user profile menu](https://docs.apigee.com/static/api-platform/images/org-list.png)
3. Click **API Proxies** on the landing page to display the API
   proxies list.

   ![Edge APIs Menu](https://docs.apigee.com/static/api-platform/images/tutorial_new_edge_apis_menu.png)
4. Click **+ Proxy** .  
   ![Create proxy button](https://docs.apigee.com/static/api-platform/images/tutorial_new_api_proxy_button.png)
5. On the **Create Proxy** page, select **Reverse proxy (most common)**.
6. On the **Proxy Details** page, 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. **Note** : For Apigee's recommendations on API versioning, see [Versioning](https://docs-apis.apigee.io/files/Web-design-the-missing-link-ebook-2016-11.pdf#page=45) in the *Web API Design: The Missing Link* e-book. |
   | **Existing API** | Enter: `http://mocktarget.apigee.net` This defines the target URL that Apigee Edge invokes on a request to the API proxy. |
   | **Description** | Enter: `hello world protected by API key` |

7. Click **Next**.
8. On the **Common Policies** page, for **Security:
   Authorization** , select **API Key** and then click **Next**. This will add two policies to your API proxy.
9. On the **Virtual Hosts** page, select **default** and **secure** and then click **Next** . Selecting **default** allows you to call your API with `http://`. Selecting **secure** , allows you to call your API with `https://`.
10. On the **Summary** page, make sure the **test** deployment environment is selected, and then click **Create and deploy**.
11. You will see an acknowledgment that your new API proxy and an API product were created successfully, and that the API proxy was deployed to your test environment.
12. Click **Edit proxy** to display the **Overview** page for the API proxy.

## View the policies

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 AssignMessage 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.
   ![](https://docs.apigee.com/static/api-platform/images/tutorial_apikey_policy-3.png)

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

   ```
   http://ORG_NAME-test.apigee.net/helloapikey
   ```

   replacing `ORG_NAME` with the name of your
   Edge organization.

   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 add an API product.

## Add an API product

To add an API product using the Apigee UI:

1. Select **Publish \> API Products**.
2. Click **+API Product**.
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. For example, `helloworld_apikey-Product`. |
   | 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. For example, `helloworld_apikey-Product`. |
   | Description | Description of the API product. For example, `Test product for tutorial`. |
   | 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 API resources section, select the API proxy you just created. For example, `helloworld_apikey`.
5. Click **Add**.
6. In the **Paths** section, add the path "/".
7. Click **Add**.
8. Click **Save**.

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

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

To create a developer:

1. Select **Publish \> Developers** in the menu.
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** | `keyser@example.com` |

4. Click **Create**.

### Register an app

To register a developer app:

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

   | In this field | do this |
   |---|---|
   | **Name** and **Display Name** | Enter: `keyser_app` |
   | **Company / Developer** | Select: `Developer` |
   | **Developer** | Select: `Keyser Soze (keyser@example.com)` |
   | **Callback URL** and **Notes** | Leave blank |

4. In the **Credentials** section, select **Never** from the **Expiry** menu. The credentials for this app will never expire.
5. Under **Products** , click **Add product**.
6. Select **helloworld_apikey-Product**.
7. Click **Add**.
8. Click **Create** above and to the right of the **App Details** section to save your work.

### Get the API key

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. In the **Product** section,
   notice that the key is associated with **helloworld_apikey**

   . ![](https://docs.apigee.com/static/api-platform/images/tutorial_helloapikey_credentials_show_key.png) ![](https://docs.apigee.com/static/api-platform/images/tutorial_helloapikey_credentials_key_displayed.png)
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. Enter
the following in your web browser. Substitute your Edge organization name
for <var translate="no">ORG_NAME</var>, and the API key for <var translate="no">API_KEY</var> below.
Make sure there are no extra spaces in the query parameter.

```
http://ORG_NAME-test.apigee.net/helloapikey?apikey=API_KEY
```

Now when you call to 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](https://docs.apigee.com/api-platform/tutorials/secure-calls-your-api-through-api-key-validation#extracreditpassingthekeyinthehttpheader).

## Best practice: Passing the key in the HTTP header

> [!NOTE]
> **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`.

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 to deploy the change.
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" http://ORG_NAME-test.apigee.net/helloapikey
   ```

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

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

> [!NOTE]
> **Note:** You could also pass the API key as a form parameter. If you did, the VerifyAPIKey policy would be configured like this:
>
> ```
> <APIKey ref="request.formparam.API_KEY"/>
> ```

## Related topics

Here are some topics that directly relate to this tutorial:

- [Manage API products](https://docs.apigee.com/api-platform/publish/create-api-products)
- [API keys](https://docs.apigee.com/api-platform/security/api-keys)
- [Register app
  developers](https://docs.apigee.com/api-platform/publish/adding-developers-your-api-product)
- [Register apps and manage API keys](https://docs.apigee.com/api-platform/publish/creating-apps-surface-your-api)
- [VerifyAPIKey
  policy](https://docs.apigee.com/api-platform/reference/policies/verify-api-key-policy)
- [AssignMessage
  policy](https://docs.apigee.com/api-platform/reference/policies/assign-message-policy)

Going a bit deeper, protecting APIs with API keys is only part of the story. Oftentimes,
API protection involves additional security such as OAuth.


[OAuth](https://docs.apigee.com/api-platform/security/oauth/oauth-home) is an
open protocol that, in a nutshell, exchanges credentials (like username and password) for
access tokens. Access tokens are long, random strings that can be passed around a message
pipeline, even from app to app, without compromising the original credentials. Access
tokens often have short lives, so new ones are always being generated.