Secure APIs with API keys

Was this helpful?

The API Platform enables you to secure your APIs with API Keys using policies, without requiring code to be written.

API key validation is the simplest form of app-based security that you can configure for an API. Apps simply present an API key, and the API Platform checks to see that the API key is in an approved state.

API keys go by many names. You can see them referred to as 'API keys', 'app keys', and 'consumer keys'. All of these names are synonymous.

Prerequisite API Key validation requires a valid API product configuration. To access a protected resource using an API key, the request must be made with an API Key approved for (at least one) API product. The topic Provision API products, developers and apps demonstrates how to set up API resources.

Sample Code This topic covers API Key-based authorization for your APIs and references the Simple Proxy in the API Platform Samples available on Github.

Back to top

Policy configuration

API keys are verified using policies of type VerifyAPIKey. The only required setting for a VerifyAPIKey policy is the expected location of the API key in the client request. API keys can be located in a query parameter, a form parameter, or an HTTP header.

For example, the policy configuration below defines the expected key location as a query parameter named apikey. A successful request must present the apikey as a query parameter appended to the request, for example,?apikey={ValueofAPIKey}.

Place the following policy in a file named APIKeyVerifier.xml under the apiproxy/policies directory:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.apikey" />
</VerifyAPIKey>
Back to top

Policy attachment

The policy must be attached to an API proxy Flow as a processing step. By applying the policy to the request PreFlow, API keys are verified on every request received by the API proxy from a client app.

Attach the policy to the ProxyEndpoint as follows:

<ProxyEndpoint name="default">
<PreFlow>
    <Request>
      <Step><Name>APIKeyVerifier</Name></Step>
    </Request>
</PreFlow>
Back to top

Importing and deploying the API proxy

For changes to take effect, you must import and deploy the modified API proxy.

If using the API Platform samples on GitHub, run:

$ sh deploy.sh

You can also call the deploy tool directly.

Substitute a valid username and password for myname:mypass for an organization on the Apigee API Platform, along with the name of the organization as myorg.

$ python tools/deploy.py -n weatherapi -u myname:mypass -h https://api.enterprise.apigee.com -o myorg -e test -p / -d simpleProxy

On import, you will see the following output. (Note that revision numbers may vary for your API proxy.)

Writing simpleProxy/apiproxy/weatherapi.xml to apiproxy/weatherapi.xml
Writing simpleProxy/apiproxy/policies/APIKeyVerifier.xml to apiproxy/policies/APIKeyVerifier.xml
Writing simpleProxy/apiproxy/proxies/default.xml to apiproxy/proxies/default.xml
Writing simpleProxy/apiproxy/targets/default.xml to apiproxy/targets/default.xml
Imported new proxy version 3
Undeploying revision 2 in same environment and path:
Environment: test
  Revision: 3 BasePath = /
  State: deployed
Back to top

Submitting a request with a valid API key

If you are using the API Platform samples on Github, run:

$ sh invoke.sh

To directly invoke the API proxy using curl, use the following examples.

You may have forgotten your API key. As as admin in your organization, you can retrieve any app's API key as follows:

As an admin for your organization, you can retrieve the consumer key for an app:

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{myorg}/developers/{developer_email}/apps/{app_name}

The app profile that is returned for this call provides the consumer key and secret. The consumer key value is the value you use for the API key in your request to the protected API.

For example, a request that does not include an API key results in an authorization failure.

$ curl http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

The failure message indicates that the policy checked for an API key but did not find a valid key:

OAuth Failure : Could not resolve the app key with variable request.queryparam.apikey

When the consumer key for the app is included as a query parameter, the expected result is successful authorization:

$ curl http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282&"apikey=PulSCqMnXGchW0pC0s5o9ngHVTWMeLqk"

The expected result is a successful response from the weather service.

Modifying the value of the API key value in the request results in an authorization failure:

$ curl http://{org_name}-test.apigee.net/weather?forecastrss?w=12797282&"apikey=PulSCqMnXGchW0"

Results in:

OAuth Failure : Consumer Key is Invalid

As an admin for your organization, you can retrieve the consumer key for an app:

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{myorg}/developers/{developer_email}/apps/{app_name}

Post questions to the Apigee Developer Forum.

Back to API Platform Developer Guide.

Back to top