Send Docs Feedback

Part 1: Deploy OAuth token endpoint

This tutorial shows you how to use the Apigee Edge management UI to the secure your API by using OAuth access tokens.

About OAuth

OAuth is an authorization protocol that enables apps to access information on behalf of users without requiring users to divulge their username and password.

An access token is a string representing an authorization issued to the client. It is used in OAuth to provide limited access to protected resources. For this reason, OAuth access tokens are often compared to 'valet keys'.

The OAuth 2.0 specification defines different ways of creating access tokens for apps. The various mechanisms for distributing access tokens are referred to as grant types. The most basic grant type defined by OAuth 2.0 is client credentials. In this grant type, OAuth access tokens are generated in exchange for client credentials, which are consumer key-consumer secret pairs.

You configure the client credentials grant type by applying OAuth v2.0 policies to your API and adding conditional flows that dynamically enforce these policies. The policies protect your API in the following ways:

  • To obtain the access token, the app must first  supply valid consumer credentials (a key/secret pair).
  • Whenever an app makes a call to your API, it must supply a valid access token.
  • Edge policies validate that the access token presented is valid, and only then grants access to the protected requested resources.

A conditional flow is a flow whose processing steps are based on a conditional statement, such as checking whether the content type specified in the HTTP request header is "text/xml". If the statement is true, the processing step specified in the flow is executed — for example, a policy is enforced or the message is routed to a specified endpoint. If the conditional statement is false, the processing step is not implemented. In this way, you can add dynamic behavior to your API proxy.

Learn more

What you’ll do in this tutorial

This tutorial shows you how to configure OAuth 2.0 client credentials using the Apigee Edge management UI*. 

(* You can also do this by directly calling the Apigee management API, as described in OAuth.)


This tutorial builds on previous tutorials and uses an API proxy for the Yahoo! Weather API as a basis of instruction. If you haven’t already done so, please review the tutorial Part 1: Create a secure API.

When you log in to Apigee Edge for the first time at, you will see the predefined resources used in this tutorial, including:

  • weatherapi - an API proxy that you use to access the Yahoo! Weather API.
  • oauth - an API proxy that you use to generate an access token from customer credentials.
  • Premium Weather API - an API product definition.
  • Nikolai Tesla - a developer.
  • Weather App - a developer app.

The oauth API proxy provides an out-of-the-box OAuth accesstoken endpoint that supports the client credentials grant type. Each organization (even a free trial org) on Apigee Edge is provisioned with the oauth API proxy. You can begin using it as soon as you create an account on Apigee Edge.

Here's an example curl command that hits the endpoint to get an access token:

 $ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST '' -d 'code=I9dMGHAN&grant_type=authorization_code&redirect_uri=' -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' 

You can publish this API to developers who need to obtain access tokens. 

Step 1: Deploy the API proxies

This tutorial predefines the weatherapi and oauth proxies for you. However, you must deploy these API proxies.

  1. Login to
  2. In the management UI, select the APIs tab.
  3. On the API Proxies page, select oauth.
  4. Select the Deployment button, and then select test from the dropdown menu. The API proxy will be deployed to the test environment.
  5. Select Deploy in the pop up window to deploy the API proxy.
  6. In the management UI, select the APIs tab.
  7. On the API Proxies page, select weatherapi.
  8. Select the Deployment button, and then select test from the dropdown menu. The API proxy will be deployed to the test environment.
  9. Select Deploy in the pop up window to deploy the API proxy.

Step 2: Examine the policies in the OAuth token endpoint

The oauth token endpoint defines two policies and two conditional flows that control the generation of access tokens. Examine these policies and flows before generating a token.

  1. In the management UI, select the APIs tab.
  2. On the API Proxies page, select oauth.
  3. Open the API Proxy Editor by clicking the Develop tab in the details page for the oauth API proxy.

    Notice that two policies have been added to your API proxy’s request message flow:

    Policy Name Policy Type     Description
    GenerateAccessTokenClient Oauth v2.0 Generates an access token from a customer key and customer secret. The access token has a duration of one hour.
    RefreshAccessToken Oauth v2.0 Not used in this tutorial and not supported for the client credentials grant type. 

    Also notice that two conditional flows have been added:

    Flow Name Description
    RefreshAccessToken Not used in this tutorial and not supported for the client credentials grant type. 
    AccessTokenClientCredential The flow that implements the GenerateAccessTokenClient policy.

The GenerateAccessTokenClient Policy

The GenerateAccessTokenClient policy is a policy of type OAuth v2.0 that generates an access token from a customer key and customer secret. You can view the XML for the policy in the Code view area of the API Proxy Editor. The XML for the policy should look like this:

<OAuthV2 name="GenerateAccessTokenClient">
  <!-- This policy generates an OAuth 2.0 access token 
       using the client_credentials grant type -->
  <!-- This is in millseconds, so expire in an hour -->
    <!-- This part is very important: most real OAuth 2.0 apps will want to use other
         grant types. In this case it is important to NOT include the "client_credentials"
         type because it allows a client to get access to a token with 
         no user authentication -->


Policy setting value Description
<Operation>GenerateAccessToken</Operation> The operation to be executed by the OAuth v2.0 policy. By specifying GenerateAccessToken, you configure the policy to generate access tokens for apps.
<ExpiresIn>3600000</ExpiresIn> Specifies the time in milliseconds for which access tokens are valid. In this case, the value specifies 3600000 milliseconds, which means a generated access token is valid for one hour.
Defines the grant types that this token endpoint supports. A token endpoint can be configured to support more than one grant type. For a list of supported grant types, see Authorize requests using OAuth 2.0.
Specifies the location in the request message where the app indicates the desired grant type. The location can be the HTTP header, a query parameter, or a form parameter. The value request.queryparam.grant_type specifies that the desired grant type is specified in a query parameter named grant_type.

The AccessToken flow

The condition proxy.pathsuffix MatchesPath &quot;/accesstoken&quot;) and (request.verb = &quot;POST&quot; specifies the following:

  • The variable: proxy.pathsuffix. Apigee Edge sets the proxy.pathsuffix variable with the fragment of a request URI that follows the URI base path.
  • The operator: MatchesPath
  • The value: &quot;/accesstoken&quot;) and (request.verb = &quot;POST&quot;

    Note: The value uses the HTML &quot; code for " (double quote character). You do not have to use the HTML code, but can insert " directly.

How it works at runtime
To request an access token, an app makes the following POST request:
  • {org} is your organization.
  • {env} is the environment, such as test.
  • accesstoken is the fragment of the URI that follows the URI base path in these access token requests.
  • grant_type specifies the grant type of the access token.
When the value of proxy.pathsuffix matches /accesstoken for a POST request, the GenerateAccessTokenClient policy is applied. (Because the proxy.pathsuffix value for all requests to obtain an access token is /accesstoken, the GenerateAccessTokenClient policy is applied for all requests.)

The RefreshAccessToken policy and flow

Refresh tokens are not supported for the client credentails grant type, and these items are not used in this tutorial. 

Step 3: Where to next?

Now that you have deployed and examined the OAuth API proxy and policies, you can add OAuth support to an API proxy.

Continue on to Part 2: Apply OAuth policies to your API to add OAuth support to an API proxy.

Help or comments?