Send Docs Feedback

Secure an API by requiring API keys

What you'll learn

Through this tutorial, you'll learn to:

  • Create an API proxy that requires an API key.
  • 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.
  • A web browser to make an API call.
  • (For the extra credit section, not required) cURL 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

The target returns Hello, Guest!. Use the /help resource to get a help page of other API resources that are available

  1. Go to https://enterprise.apigee.com and log in. This is the Edge management UI.
  2. Click APIs in the top menu.
  3. Click the add (+) API Proxy button.
  4. In the Build a Proxy wizard, select Reverse proxy (most common), and click Next.
  5. Configure the proxy with the following:
    In this field do this
    Proxy Name Enter: helloworld_apikey
    Project Base Path

    Change to: /v1/helloapikey

    The Project Base Path is part of the URL used to make requests to the API proxy.

    Adding a version number is considered a best practice to version your API. For more information on this important topic, see Versioning Best Practices.

    Existing API

    Enter: http://mocktarget.apigee.net

    Be sure to use http and not https. This defines the target URL that Apigee Edge invokes on a request to the API proxy.

    Description Enter: hello world protected by API key
  6. Click Next.
  7. On the Security page:
    In this field do this
    Authorization Select:
    • API Key
    • Publish API Product

    These options are very handy. They'll automatically add two policies to your API proxy and create an API product needed for generating the API key.

  8. On the Virtual Hosts page, click Next.
  9. On the Build page, make sure the test environment is selected, and click Build and Deploy.
  10. On the Summary page, you 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.
  11. Click View the helloworld_apikey proxy in the editor 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 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 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/v1/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 get the required API key.

About the API product

Without getting into too much detail for this tutorial, an API product in Edge (among other nifty features) generates API keys for developers; or more accurately, for the apps developers register with Edge.

If you're curious, you can view the API product that was automatically created when your API proxy was generated. Select Publish > Products > helloworld_apikey Product in the UI.

Notice that the Key Approval Type is Automatic. That means developers get an API key automatically when they register an app, as opposed to you manually approving keys before they're given to developers.

Moving on.

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 do this
    First Name Enter: Keyser
    Last Name Enter: Soze
    Email Enter: keyser@example.com
    Username Enter: keyser
  4. Click Save.

Register an app

To register a developer app:

  1. Select Publish > Developer Apps.
  2. Click + Developer App.
  3. Enter the following in the New Developer App window:
    In this field do this
    Name and Display Name Enter: keyser_app
    Developer Select: Keyser Soze (keyser@example.com)
    Callback URL and Notes Leave blank
  4. Under Products, click + Product.
  5. Select helloworld_apikey Product.
  6. Click Save.

Get the API key

To get the API key:

  1. On the Developer Apps page (Publish > Developer Apps), click keyser_app.
  2. On the keyser_app page, click Show in the Consumer Key column. Notice that the key is associated with the "helloworld_apikey Product".
  3. Select and copy the Consumer 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 {org-name}, and paste the API (Consumer) key as shown, as a query parameter. Make sure there are no extra spaces in the query parameter.

http://{org-name}-test.apigee.net/v1/helloapikey?apikey={paste_api_key_here}

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.

Extra credit: Passing the key in the HTTP header

This step isn't required, but it gives you a different way that the API key can be provided: in the HTTP header instead of as a query parameter.

  1. Edit the API proxy. Select APIs > 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.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 apikey. Don't forget to substitute your organization name.

    curl -v -H "apikey: {api_key_goes_here}" http://{org-name}-test.apigee.net/v1/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.

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.apikey"/>

Related topics

Here are some topics that directly relate to this tutorial:

Going it bit deeper, protecting APIs with API keys is only part of the story. Oftentimes, API protection involves additional security such as OAuth. Here are a couple of topics that describe other security features:

  • OAuth – OAuth 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.
  • StreetCarts project – Built on Apigee Edge, StreetCarts is a sample API for food trucks. It uses API proxies with API BaaS as a data store. Security includes API keys, OAuth, a vault to store credentials, and role-based access control.
  • For the rest, see the "Secure" section of the Apigee Edge documentation.

 

Help or comments?