This pageapplies toApigee andApigee hybrid.

View Apigee Edge documentation.

This document shows you how to get OAuth 2.0 access tokens and authorization codes with the Apigee API. We also show how to create policies for each OAuth 2.0 grant type and configure proxy endpoints to accept client requests.

Use the authorization code grant type

This section explains how to get an access token using the authorization code grant type flow. The token request for this flow requires an authorization code. SeeGet an authorization code. See alsoWhat are OAuth 2.0 grant types.

Sample request

curl -i -H 'Content-Type: application/x-www-form-urlencoded' \   -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \   -X POST 'https://apitest.acme.com/oauth/token' \   -d 'code=I9dMGHAN&grant_type=authorization_code&redirect_uri=http://example-callback.com'

Required parameters

By default, these parameters must bex-www-form-urlencoded and specified in the request body (as shown in the sample above); however, it is possible to change this default by configuring the<GrantType>,<Code>, and<RedirectUri> elements in the OAuthV2 policy. SeeOAuthV2 policy.

• grant_type - Must be set to the valueauthorization_code.
• code - The authorization code. See Requesting an authorization code.
• redirect_uri - You must provide this parameter if theredirect_uri parameter was included in the authorization code request. If theredirect_uri parameter was not included in the authorization code request, and if you do not provide this parameter, then this policy uses the value of the Callback URL provided in the registered developer app.

Optional parameters

• state - A string that will be sent back with the response. Typically used to prevent cross-site request forgery attacks.
• scope - Allows you to filter the list of API products with which the minted token can be used. For detailed information on scope, seeWorking with OAuth2 scopes.

Authorization

You must pass the Client ID and Client Secret either as a Basic Authorization header (Base64-encoded) or as form parametersclient_id andclient_secret. You obtain these values from a registered developer app. See alsoEncoding basic authentication credentials.

Sample endpoint

Here's a sample endpoint configuration for generating an access token. It'll execute the GenerateAccessToken policy, which must be configured to support the authorization_code grant type.

...       <Flow name="generate-access-token">            <Description>Generate a token</Description>            <Request>                <Step>                    <Name>GenerateAccessToken</Name>                </Step>            </Request>            <Response/>            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>        </Flow>...

Sample policy

This is a basic GenerateAccessToken policy that is configured to accept theauthorization_code grant type. For information on optional configuration elements that you can configure with this policy, seeOAuthV2 policy.

<OAuthV2 name="GenerateAccessToken">    <Operation>GenerateAccessToken</Operation>    <ExpiresIn>1800000</ExpiresIn>    <RefreshTokenExpiresIn>86400000</RefreshTokenExpiresIn>    <SupportedGrantTypes>      <GrantType>authorization_code</GrantType>    </SupportedGrantTypes>    <GenerateResponse enabled="true"/></OAuthV2>

Returns

With<GenerateResponse> enabled, the policy returns a JSON response that includes the access token, as shown below. Theauthorization_code grant type creates an access token and a refresh tokens, so a response might look like this:

{"issued_at":"1420262924658","scope":"READ","application_name":"ce1e94a2-9c3e-42fa-a2c6-1ee01815476b","refresh_token_issued_at":"1420262924658","status":"approved","refresh_token_status":"approved","api_product_list":"[PremiumWeatherAPI]","expires_in":"1799",//--in seconds"developer.email":"tesla@weathersample.com","organization_id":"0","token_type":"BearerToken","refresh_token":"fYACGW7OCPtCNDEnRSnqFlEgogboFPMm","client_id":"5jUAdGv9pBouF0wOH5keAVI35GBtx3dT","access_token":"2l4IQtZXbn5WBJdL6EF7uenOWRsi","organization_name":"docs","refresh_token_expires_in":"86399",//--in seconds"refresh_count":"0"}

oauthv2accesstoken.{policy-name}.access_tokenoauthv2accesstoken.{policy-name}.expires_in //--in secondsoauthv2accesstoken.{policy-name}.refresh_tokenoauthv2accesstoken.{policy-name}.refresh_token_expires_in //--in secondsoauthv2accesstoken.{policy-name}.refresh_token_issued_atoauthv2accesstoken.{policy-name}.refresh_token_status

oauthv2accesstoken.GenerateAccessToken.access_tokenoauthv2accesstoken.GenerateAccessToken.expires_inoauthv2accesstoken.GenerateAccessToken.refresh_tokenoauthv2accesstoken.GenerateAccessToken.refresh_token_expires_inoauthv2accesstoken.GenerateAccessToken.refresh_token_issued_atoauthv2accesstoken.GenerateAccessToken.refresh_token_status

This section explains how to get an access token using the client credentials grant type flow. See alsoWhat are OAuth 2.0 grant types.

Sample request

curl -H "Content-Type: application/x-www-form-urlencoded" \  -H "Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" \  -X POST "https://apitest.acme.com/oauth/token" \  -d "grant_type=client_credentials"

Required parameters

• grant_type - Must be set to the valueclient_credentials.

  By default, the requiredgrant_type parameter must bex-www-form-urlencoded and specified in the request body (as shown in the sample above); however, it is possible to change this default by configuring the<GrantType> element in the OAuthV2 policy. For example, you could elect to pass the parameter in a query parameter. For details, seeOAuthV2 policy.

Optional parameters

• state - A string that will be sent back with the response. Typically used to prevent cross-site request forgery attacks.
• scope - Allows you to filter the list of API products with which the minted token can be used. For detailed information on scope, seeWorking with OAuth2 scopes.

Authorization

You must pass the Client ID and Client Secret either as a Basic Authorization header (Base64-encoded) or as form parametersclient_id andclient_secret. You obtain these values from the registered developer app associated with the request. See alsoEncoding basic authentication credentials.

Sample endpoint

Here's a sample endpoint configuration for generating an access token. It'll execute the GenerateAccessToken policy, which must be configured to support the client_credentials grant type.

...       <Flow name="generate-access-token">            <Request>                <Step>                    <Name>GenerateAccessToken</Name>                </Step>            </Request>            <Response/>            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>        </Flow>...

Sample policy

This is a basic GenerateAccessToken policy that is configured to accept theclient_credentials grant type. For information on optional configuration elements that you can configure with this policy, seeOAuthV2 policy.

<OAuthV2 name="GenerateAccessToken">    <Operation>GenerateAccessToken</Operation>    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->    <SupportedGrantTypes>      <GrantType>client_credentials</GrantType>    </SupportedGrantTypes>    <GenerateResponse enabled="true"/></OAuthV2>

Returns

With<GenerateResponse> enabled, the policy returns a JSON response. Note that with theclient_credentials grant type, refresh tokens are not supported. Only an access token is minted. For example:

{"issued_at":"1420260525643","application_name":"ce1e94a2-9c3e-42fa-a2c6-1ee01815476b","scope":"READ","status":"approved","api_product_list":"[PremiumWeatherAPI]","expires_in":"1799",//--in seconds"developer.email":"tesla@weathersample.com","organization_id":"0","token_type":"BearerToken","client_id":"5jUAdGv9pBouF0wOH5keAVI35GBtx3dT","access_token":"XkhU2DFnMGIVL2hvsRHLM00hRWav","organization_name":"docs"}

If<GenerateResponse> is set to false, the policy does not return a response. Instead, it populates the following set of flow variables with data pertaining to the access token grant.

oauthv2accesstoken.{policy-name}.access_tokenoauthv2accesstoken.{policy-name}.expires_in //--in seconds

For example:

oauthv2accesstoken.GenerateAccessToken.access_tokenoauthv2accesstoken.GenerateAccessToken.expires_in     //--in seconds

Use the password grant type

This section explains how to get an access token using the resource owner password credentials (password) grant type flow. See alsoImplementing the password grant type. See alsoWhat are OAuth 2.0 grant types.

Sample request

curl -v -k -H "Content-Type: application/x-www-form-urlencoded" \  -H "Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" \  -X POST "https://apitest.acme.com/oauth/token" \  -d "grant_type=password&username=a_username&password=a_password"

Required parameters

By default, these parameters must bex-www-form-urlencoded and specified in the request body (as shown in the sample above); however, it is possible to change this default by configuring the<GrantType>,<Username>, and<Password> elements in the OAuthV2 policy. SeeOAuthV2 policy.

User credentials are typically validated against a credential store using an LDAP or JavaScript policy.

• grant_type - Must be set to the valuepassword.
• username - The resource owner's user name.
• password - The resource owner's password.

Optional parameters

• state - A string that will be sent back with the response. Typically used to prevent cross-site request forgery attacks.
• scope - Allows you to filter the list of API products with which the minted token can be used. For detailed information on scope, seeWorking with OAuth2 scopes.

Authorization

You must pass the Client ID and Client Secret either as a Basic Authorization header (Base64-encoded) or as form parametersclient_id andclient_secret. You obtain these values from the registered developer app associated with the request. See alsoEncoding basic authentication credentials.

Sample endpoint

Here's a sample endpoint configuration for generating an access token. It'll execute the GenerateAccessToken policy, which must be configured to support the password grant type.

...       <Flow name="generate-access-token">            <Request>                <Step>                    <Name>GenerateAccessToken</Name>                </Step>            </Request>            <Response/>            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>        </Flow>...

Sample policy

This is a basic GenerateAccessToken policy that is configured to accept the password grant type. For information on optional configuration elements that you can configure with this policy, seeOAuthV2 policy.

<OAuthV2 name="GenerateAccessToken">    <Operation>GenerateAccessToken</Operation>    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->    <SupportedGrantTypes>      <GrantType>password</GrantType>    </SupportedGrantTypes>    <GenerateResponse enabled="true"/></OAuthV2>

Returns

With<GenerateResponse> enabled, the policy returns a JSON response. Note that with the password grant type, both an access token and refresh token are minted. For example:

{"issued_at":"1420258685042","scope":"READ","application_name":"ce1e94a2-9c3e-42fa-a2c6-1ee01815476b","refresh_token_issued_at":"1420258685042","status":"approved","refresh_token_status":"approved","api_product_list":"[PremiumWeatherAPI]","expires_in":"1799",//--in seconds"developer.email":"tesla@weathersample.com","organization_id":"0","token_type":"BearerToken","refresh_token":"IFl7jlijYuexu6XVSSjLMJq8SVXGOAAq","client_id":"5jUAdGv9pBouF0wOH5keAVI35GBtx3dT","access_token":"I6daIgMSiUgYX1K2qgQWPi37ztS6","organization_name":"docs","refresh_token_expires_in":"28799",//--in seconds"refresh_count":"0"}

If<GenerateResponse> is set to false, the policy does not return a response. Instead, it populates the following set of flow variables with data pertaining to the access token grant.

oauthv2accesstoken.{policy-name}.access_tokenoauthv2accesstoken.{policy-name}.expires_in   //--in secondsoauthv2accesstoken.{policy-name}.refresh_tokenoauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in secondsoauthv2accesstoken.{policy-name}.refresh_token_issued_atoauthv2accesstoken.{policy-name}.refresh_token_status

For example:

oauthv2accesstoken.GenerateAccessToken.access_tokenoauthv2accesstoken.GenerateAccessToken.expires_inoauthv2accesstoken.GenerateAccessToken.refresh_tokenoauthv2accesstoken.GenerateAccessToken.refresh_token_expires_inoauthv2accesstoken.GenerateAccessToken.refresh_token_issued_atoauthv2accesstoken.GenerateAccessToken.refresh_token_status

Use the implicit grant type

This section explains how to get an access token using the implicit grant type flow. See alsoWhat are OAuth 2.0 grant types.

Sample request

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \  'https://apitest.acme.com/oauth/implicit?response_type=token&client_id=c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ&redirect_uri=http://callback-example.com'

Required parameters

By default, these parameters must be query parameters (as shown in the sample above); however, it is possible to change this default by configuring the<ResponseType>,<ClientId>, and<RedirectUri> elements in the OAuthV2 policy that is attached to this/token endpoint. For details, seeOAuthV2 policy.

User credentials are typically validated against a credential store using an LDAP service callout or JavaScript policy.

• response_type - Must be set to the valuetoken.
• client_id - The client ID of a registered developer app.
• redirect_uri - This parameter is mandatory if a Callback URI was not provided when the client developer app was registered. If a Callback URL was provided at client registration, it will be compared to this value and must match exactly.

Optional parameters

• state - A string that will be sent back with the response. Typically used to prevent cross-site request forgery attacks.
• scope - Allows you to filter the list of API products with which the minted token can be used. For detailed information on scope, seeWorking with OAuth2 scopes.

Authorization

Does not require the Authorization header; however, you do need to pass a client ID as a request parameter.

Sample endpoint

Here's a sample endpoint configuration for generating an access token. It'll execute the GenerateAccessTokenImplicitGrant policy.

...<Flowname="generate-access-token-implicit"><Request><Step><Name>GenerateAccessTokenImplicitGrant</Name></Step></Request><Response/><Condition>(proxy.pathsuffixMatchesPath"/implicit")and(request.verb="POST")</Condition></Flow>...

Sample policy

This is a basic GenerateAccessTokenImplicitGrant policy that processes token requests for the implicit grant type flow. For information on optional configuration elements that you can configure with this policy, seeOAuthV2 policy.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><OAuthV2 name="GenerateAccessTokenImplicit">    <DisplayName>GenerateAccessTokenImplicit</DisplayName>    <Operation>GenerateAccessTokenImplicitGrant</Operation>    <GenerateResponse enabled="true"/></OAuthV2>

Returns

With<GenerateResponse> enabled, the policy returns a 302 Location redirect in the response header. The redirect points to the URL specified in theredirect_uri parameter and is appended with the access token and token expiration time. Note that the implicit grant type does not support refresh tokens. For example:

https://callback-example.com#expires_in=1799&access_token=In4dKm4ueoGZRbIYJhC9yZCmTFw5

If<GenerateResponse> is set to false, the policy does not return a response. Instead, it populates the following set of flow variables with data pertaining to the access token grant.

oauthv2accesstoken.{policy-name}.access_tokenoauthv2accesstoken.{policy-name}.expires_in  //--in seconds

For example:

oauthv2accesstoken.GenerateAccessToken.access_tokenoauthv2accesstoken.GenerateAccessToken.expires_in   //--in seconds

Get an authorization code

In the authorization code grant type flow, an authorization code is required to obtain an access token. SeeUse the authorization code grant type. See alsoWhat are OAuth 2.0 grant types.

Sample request

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \  "https://apitest.acme.com/oauth/authorize?response_type=code&client_id=c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ&redirect_uri=http://my-callback.com"

Required parameters

By default, these parameters must be query parameters (as shown in the sample above); however, it is possible to change this default by configuring the<ResponseType>,<ClientId>, and<RedirectUri> elements in the OAuthV2 policy. For details, seeOAuthV2 policy.

• redirect_uri - If a full (not partial) Callback URI is specified in the registered client app, this parameter is optional; otherwise, it is required. The callback is the URL where Apigee sends the newly minted auth code. See alsoRegister apps and manage API keys.
• response_type - Must be set to the valuecode.
• client_id - The client ID of a registered developer app.

Optional parameters

• redirect_uri - If a full (not partial) Callback URI is specified in the registered client app, this parameter is optional; otherwise, it is required. The callback is the URL where Apigee sends the newly minted auth code. See alsoRegister apps and manage API keys.
• state - A string that will be sent back with the response. Typically used to prevent cross-site request forgery attacks.
• scope - Allows you to filter the list of API products with which the minted token can be used. For detailed information on scope, seeWorking with OAuth2 scopes.

Authorization

Does not require the Authorization header, however the client ID of the registered client app must be supplied in the request.

Sample policy

This is a basic GenerateAuthorizationCode policy. For more configuration options, seeOAuthV2 policy:

<OAuthV2 name="GenerateAuthorizationCode">    <Operation>GenerateAuthorizationCode</Operation>    <GenerateResponse enabled="true"/></OAuthV2>

Returns

With<GenerateResponse> enabled, the policy returns?code query parameter to theredirect_uri (Callback URI) location with the authorization code attached. It is sent via a 302 browser redirect with the URL in the Location header of the response. For example:?code=123456.

If<GenerateResponse> is set tofalse, the policy does not return a response. Instead, it populates the following set of flow variables with data pertaining to the authorization code.

oauthv2authcode.{policy-name}.codeoauthv2authcode.{policy-name}.scopeoauthv2authcode.{policy-name}.redirect_urioauthv2authcode.{policy-name}.client_id

For example:

oauthv2authcode.GenerateAuthorizationCode.codeoauthv2authcode.GenerateAuthorizationCode.scopeoauthv2authcode.GenerateAuthorizationCode.redirect_urioauthv2authcode.GenerateAuthorizationCode.client_id

Refreshing an access token

A refresh token is a credential you use to obtain an access token, typically after the access token has expired or becomes invalid. A refresh token is returned in the response when you receive an access token.

For information on encoding the basic authentication header in the following call, seeEncoding basic authentication credentials.

$ curl -X POST \  -H "Content-type: application/x-www-form-urlencoded" \  -H "Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" \  https://apitest.acme.com/oauth/refresh \  -d "grant_type=refresh_token&refresh_token=yVSL38WpuN3Kzn1UTMoE6AQ4ANZM"

Required parameters

By default, the policy looks for these asx-www-form-urlencoded parameters specified in the request body, as shown in the example above. To configure an alternate location for these inputs, you can use the<GrantType> and<RefreshToken> elements in the OAuthV2 policy. For details, seeOAuthV2 policy.

• grant_type - Must be set to the valuerefresh_token.
• refresh_token - The refresh token associated with the access token you wish to renew.

Optional parameters

• state - A string that will be sent back with the response. Typically used to prevent cross-site request forgery attacks.
• scope - Allows you to filter the list of API products with which the minted token can be used. For detailed information on scope, seeWorking with OAuth2 scopes.

Authorization

Does not require the Authorization header, however the client ID of the registered client app must be supplied in the request.

When refreshing an access token, there is no re-authentication of the user.

Here's a sample endpoint configuration for generating an access token using a refresh token. It'll execute the RefreshAccessToken policy.

 ...       <Flow name="generate-refresh-token">            <Request>                <Step>                    <Name>RefreshAccessToken</Name>                </Step>            </Request>            <Response/>            <Condition>(proxy.pathsuffix MatchesPath "/refresh") and (request.verb = "POST")</Condition>       </Flow>...

Sample policy

This is a basic RefreshAccessToken policy that is configured to accept therefresh_token grant type. For information on optional configuration elements that you can configure with this policy, seeOAuthV2 policy.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><OAuthV2 name="RefreshAccessToken">    <Operation>RefreshAccessToken</Operation>    <GenerateResponse enabled="true"/>    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours --></OAuthV2>

Returns

With<GenerateResponse> enabled, the policy returns a JSON response containing the new access token. Therefresh_token grant type supports minting both access and new refresh tokens. For example:

{"issued_at":"1420301470489","application_name":"ce1e94a2-9c3e-42fa-a2c6-1ee01815476b","scope":"READ","refresh_token_issued_at":"1420301470489","status":"approved","refresh_token_status":"approved","api_product_list":"[PremiumWeatherAPI]","expires_in":"1799",//--in seconds"developer.email":"tesla@weathersample.com","token_type":"BearerToken","refresh_token":"8fKDHLryAD9KFBsrpixlq3qPJnG2fdZ5","client_id":"5jUAdGv9pBouF0wOH5keAVI35GBtx3dT","access_token":"jmZ2Hqv3iNsABUtAAsfWR3QGNctw","organization_name":"docs","refresh_token_expires_in":"28799",//--in seconds"refresh_count":"2"}

oauthv2accesstoken.{policy-name}.access_tokenoauthv2accesstoken.{policy-name}.expires_in   //--in secondsoauthv2accesstoken.{policy-name}.refresh_tokenoauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in secondsoauthv2accesstoken.{policy-name}.refresh_token_issued_atoauthv2accesstoken.{policy-name}.refresh_token_status

oauthv2accesstoken.RefreshAccessToken.access_tokenoauthv2accesstoken.RefreshAccessToken.expires_inoauthv2accesstoken.RefreshAccessToken.refresh_tokenoauthv2accesstoken.RefreshAccessToken.refresh_token_expires_inoauthv2accesstoken.RefreshAccessToken.refresh_token_issued_atoauthv2accesstoken.RefreshAccessToken.refresh_token_status

Encoding basic authentication credentials

When you make an API call to request a token or auth code, it's a good practice, and is recommended by the OAuth 2.0 specification to pass the client_id and client_secret values as an HTTP-Basic Authorization header, as described inIETF RFC 2617. To do this, you must base64-encode the result of joining the two values together with a colon separating them.

In pseudo-code:

result = Base64Encode(concat('ns4fQc14Zg4hKFCNaSzArVuwszX95X', ':', 'ZIjFyTsNgQNyxI'))

Where:ns4fQc14Zg4hKFCNaSzArVuwszX95X is the client_id andZIjFyTsNgQNyxI is the client secret.

Examples

This example command works on Linux and MacOS:

export CREDENTIALS=$(echo -n 'ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI' | base64)

Then, you can make the token request as follows:

$ curl -i -H "Content-Type: application/x-www-form-urlencoded" \  -H "Authorization: Basic $CREDENTIALS" \  -X POST "https://apitest.acme.com/oauth/token" \  -d "grant_type=client_credentials"

Hashing tokens in the database

Apigee hashes all OAuth access and refresh tokens to protect them in the event of a database security breach. You use non-hashed tokens in API calls, and Apigee validates them against the hashed versions in the database.

Related topics

• Implementing the client credentials grant type
• Implementing the authorization code grant type
• API security online course (includes OAuth)
• OAuthV2 policy -- Has lots of examples showing how to make requests to the authorization server and how to configure the OAuthV2 policy.