Part 2: Generate and test an API key

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation.
info

Refactored and redirected to Secure an API by requiring API keys.

A developer builds an app that makes requests to your APIs to access your backend services. To control access to your APIs, you can require the developer to pass an API key on every request. If the key is missing or invalid, the request fails.

Publishing is the process of making your APIs available to app developers for consumption. Publishing APIs can be broadly defined by the following tasks:

  1. Create the API products on Apigee Edge that bundle your APIs.
  2. Register app developers on Edge. Only a registered app developer can register an app.
  3. Developers register apps on Edge to access API products. In response, the developer receives an API key. Now that the developer has an API key, they can make requests to your APIs.

For more, see Introduction to publishing.

The following table defines some of the terms used to register apps and generate keys:

Term Definition
API product A bundle of API proxies combined with a service plan that sets limits on access to those APIs. API products are the central mechanism that Apigee Edge uses for authorization and access control to your APIs.
Developer The API consumer. Developers write apps that make requests to your APIs.
App A client-side app that a developer registers to access an API product. Registering the app with the API product generates the API key for accessing the APIs in that product.
API key A string with authorization information that a client-side app uses to access the resources exposed by the API product. The API key is generated when a registered app is associated with an API product.

Prerequisites for this tutorial

This tutorial assumes that you have completed the first tutorial, where you create an API proxy to access the Yahoo weather API. If you have not yet completed the first tutorial, see Secure an API by requiring API keys.

Step 1: Create an API product

  1. In the management UI, click the Publish tab, then Products.
  2. Click (+) Product.
  3. Enter or select the following in the Add Product dialog fields:
    Field Value
    Name Free API Product
    Display Name Free API Product
    Description Free API Product
    Environment test
    Access Internal only
    Key approval type Automatic
    (the API key is automatically approved after it has been generated)
    Quota 10 requests per 1 hour
    (limits the number of requests to 10 per hour)
    Allowed OAuth Scopes leave blank

    The filled-in dialog should look like this:

  4. In the Resources section, choose:
    • API Proxy: weatherapikey
    • Revision: 1
    • Resource Path: /forecastrss**

      The Resource Path specifies the resource URIs that the product allows an app to access. In this example, an app can only access the /forecastrss resource on the weatherapikey proxy through this API product. Trying to use this API product to access any other resource on the weatherapiproxy proxy, or on any other proxy, is forbidden.

      Wildcard characters are allowed for the Resource Path. The wildcard "/**" indicates that all sub-URIs are included, meaning a resource in the form /forecastrss/foo/bar. The wildcard "/" indicates that only URIs one level down are included. See Create API products for more.

      Note that the Resource Path dropdown list shows all of the conditional flows defined on the specified API proxy. An API proxy's conditional flow defines the logic, or processing steps, associated with a resource path. An API product controls access to those resource paths.
  5. Click Import Resource. The resource path is added, and the weatherapikey API proxy is automatically added to the API Proxies for Product section.
  6. Click Save. Your new product is listed on the Products page.

Learn more:

Step 2: Register a developer

To generate an API key, you register an app and associate it with an API product. However, you can't register an app without first registering the developer of the app.

  1. In the management UI, click the Publish tab, then Developers.
  2. Click (+) Developer.
  3. In the New Developer dialog, enter the following values:
    • First Name: Jane
    • Last Name: Tutorial
    • Email address: janetutorial@example.com
    • Username: jtutorial
  4. Click Save. The new developer appears in the list of developers on the Developers page.

Learn more:

Step 3: Register the app

Now that you have an API product and a developer, you can register an app with the API product. Registering the app generates the API key for the API products associated with the app. You can then distribute the key to app developers so they can access the features in the API products from the app.

  1. In the API Platform UI, click the Publish tab, then Developer Apps.
  2. Click (+) Developer App.
  3. In the Add an App dialog, enter the following values:
    • Display Name: Weather API Key App
    • Developer: Jane Tutorial (janetutorial@example.com)
    • Callback URL: leave blank
  4. Associate the app with a product:
    1. In the Products section, click + Product.
    2. Select Free API Product.
    3. Click the check mark icon to accept the changes.
  5. Click Save. The new app appears in the list of apps on the Developer Apps page.
  6. Select Weather API Key App in the list of apps. This opens the details page for the app.
  7. Because you selected Key Approval Type: Automatic when you created the API product, the API key is automatically approved and you can view it immediately. (If you had selected Approval Type: Manual, you would need to click Approve in the Actions column for Free API Product to approve the API key.)
  8. In the Products section, next to the entry for Free API Product, click Show in the Consumer Key and Consumer Secret columns to display the generated keys.

    The Consumer Key is another name for the API key and is the only key an app needs to access the forecast resource through your API proxy . The Consumer Secret is needed (along with the Consumer Key) in securing an API through OAuth 2.0. See, for example, OAuth 2.0: Configuring a new API proxy.

Learn more:

Step 4: Use the API key in a request

To ensure that the VerifyAPIKey policy is working correctly, you need to test it by making a call to the API proxy with a valid API key. You can request the API proxy in a browser, from the Trace page of the API proxy, from the Apigee Console, or by using cURL. The URL to request is in the form:

http://{org-name}-test.apigee.net/v1/weatherapikey/forecastrss?w=12797282&apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls

Substitute your Apigee organization name for {org-name} and the correct apikey value.

Look for the following content in the response:

<rss xmlns:yweather="http://xml.weather.yahoo.com/ns/rss/1.0" xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#" version="2.0"> 
<channel> <title>Yahoo! Weather - Palo Alto, CA</title> 
<link>http://us.rd.yahoo.com/dailynews/rss/weather/Palo_Alto__CA/*http://weather.yahoo.com/forecast/USCA1093_f.html</link> 
<description>Yahoo! Weather for Palo Alto, CA</description> <language>en-us</language>

If you omit the API key from the request, or specify an invalid key value, you will receive an error response in the form:

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

Step 5: Where to next?

Now that you have made a request to the API by using a query parameter to pass the api key, modify the API to pass the key as a header.

Continue on to Secure an API by requiring API keys.