You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/reference/policies/revoke-oauth-v2-policy). info
![policy icon](https://docs.apigee.com/static/api-platform/images/icon_policy_security.jpg)

## Overview

Revokes OAuth2 access tokens associated with a developer app ID or app end user ID, or both.

> [!WARNING]
> **Warning:**OAuth tokens are cached for three minutes (180 seconds); therefore, a revoked token may still succeed for up to three minutes, until its cache limit expires.

> [!WARNING]
> **Warning:** You can potentially revoke a large number of tokens with a single execution of this policy. Because you cannot undo the revocation of a token, ensure that the ID you pass to this policy specifying the tokens to revoke is correct.

> [!NOTE]
> **Note:** `RevokeOAuthV2` is not available in Apigee Edge for Private Cloud.

Use the [OAuthv2 policy](https://docs.apigee.com/api-platform/reference/policies/oauthv2-policy) to generate an OAuth 2.0 access token. An Apigee generated token
has the following format:

```
{
  "issued_at" : "1421847736581",
  "application_name" : "a68d01f8-b15c-4be3-b800-ceae8c456f5a",
  "scope" : "READ",
  "status" : "approved",
  "api_product_list" : "[PremiumWeatherAPI]",
  "expires_in" : "3599", //--in seconds
  "developer.email" : "tesla@weathersample.com",
  "organization_id" : "0",
  "token_type" : "BearerToken",
  "client_id" : "k3nJyFJIA3p62DWOkLO6OJNi87GYXFmP",
  "access_token" : "7S22UqXGJDTuUADGzJzjXzXSaGJL",
  "organization_name" : "myorg",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}
```

The `application_name` element contains the developer app ID associated with the token.

By default, Apigee does not include the end user ID in the token. You can configure Apigee to include
the end user ID by adding the `<AppEndUser>` element to the [OAuthv2 policy](https://docs.apigee.com/api-platform/reference/policies/oauthv2-policy):

```
<OAuthV2 name="GenerateAccessTokenClient">
    <Operation>GenerateAccessTokenV/Operation>
    ...
    <AppEndUser>request.queryparam.app_enduser</AppEndUser>
</OAuthV2>
```

In this example, pass the end user ID to the [OAuthv2 policy](https://docs.apigee.com/api-platform/reference/policies/oauthv2-policy) in a query parameter named `app_enduser`.
The end user ID is then included in the token in the `app_enduser` element:

```
{
 "issued_at" : "1421847736581",
 "application_name" : "a68d01f8-b15c-4be3-b800-ceae8c456f5a",
 "scope" : "READ",
 "app_enduser" : "6ZG094fgnjNf02EK",
 "status" : "approved",
 "api_product_list" : "[PremiumWeatherAPI]",
 "expires_in" : "3599", //--in seconds
 "developer.email" : "tesla@weathersample.com",
 "organization_id" : "0",
 "token_type" : "BearerToken",
 "client_id" : "k3nJyFJIA3p62DWOkLO6OJNi87GYXFmP",
 "access_token" : "7S22UqXGJDTuUADGzJzjXzXSaGJL",
 "organization_name" : "myorg",
 "refresh_token_expires_in" : "0", //--in seconds
 "refresh_count" : "0"
}
```

## Revoke by developer app ID

Revoke OAuth2 access tokens associated with a developer app ID.
All OAuth2 access tokens generated by Apigee include the ID of the developer app associated
with the token. You can then revoke tokens based on that app ID.

- Use the [Developer apps API](https://apidocs.apigee.com/docs/developer-apps/1/routes/organizations/%7Borg_name%7D/developers/%7Bdeveloper_email%7D/apps/get) to get a list of app IDs for a specific developer.

- You can also use the [Developer apps API](https://apidocs.apigee.com/docs/developer-apps/1/routes/organizations/%7Borg_name%7D/developers/%7Bdeveloper_email%7D/apps/%7Bapp_name%7D/get)
  to get details about an app.

## Revoke by app end-user ID

Revoke OAuth2 access tokens associated with a specific app end-user's ID. This is the token
associated with the ID of the user to whom the tokens were issued.

By default, there is no field for end user ID in the OAuth access token. To enable revocation of
OAuth 2.0 access tokens by end user ID, you have to configure the [OAuthv2 policy](https://docs.apigee.com/api-platform/reference/policies/oauthv2-policy) to include the user ID
in the token, as shown above.

To get an app end-user ID, use the
[Developer apps API](https://apidocs.apigee.com/docs/developer-apps/1/routes/organizations/%7Borg_name%7D/developers/%7Bdeveloper_email%7D/apps/get).

## Samples

The following samples use the Revoke OAuth V2 policy to revoke OAuth2 access tokens.

### Developer app ID

To revoke access tokens by developer app ID, use the `<AppId>` element in
your policy.

The following example expects to find the developer app ID of the access token in a query parameter named
`app_id`:

```
<RevokeOAuthV2 continueOnError="false" enabled="true" name="MyRevokeTokenPolicy">
  <DisplayName>Revoke OAuth v2.0-1</DisplayName>
  <AppId ref="request.queryparam.app_id"></AppId>
</RevokeOAuthV2>
```

Given the ID of the developer app, the policy revokes the access token.

### Revoke before timestamp

To revoke access tokens by developer app ID that were generated before a specific date and time,
use the `<RevokeBeforeTimestamp>` element in your policy. `<RevokeBeforeTimestamp>`
specifies a UTC epoch time in milliseconds. All tokens issued before that time are revoked.

The following example revokes the access tokens for a developer app created before July 1, 2019:

```
<RevokeOAuthV2 continueOnError="false" enabled="true" name="MyRevokeTokenPolicy">
  <DisplayName>Revoke OAuth v2.0-1</DisplayName>
  <AppId ref="request.queryparam.app_id"></AppId>
  <RevokeBeforeTimestamp>1561939200000</RevokeBeforeTimestamp>
</RevokeOAuthV2>
```

The `<RevokeBeforeTimestamp>` element takes a 64-bit (long) integer representing
the number of milliseconds elapsed since midnight, on January 1, 1970 UTC.

*** ** * ** ***

## Element Reference

The element reference describes the elements and attributes of the RevokeOAuthV2 policy.

```
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<RevokeOAuthV2 continueOnError="false" enabled="true" name="GetOAuthV2Info-1">
  <DisplayName>Get OAuth v2.0 Info 1</DisplayName>
  <AppId ref="variable"></AppId>
  <EndUserId ref="variable"></EndUserId>
  <RevokeBeforeTimestamp ref="variable"></RevokeBeforeTimestamp>
  <Cascade>false</Cascade>
</RevokeOAuthV2>
```

## \<RevokeOAuthV2\> attributes

```
<RevokeOAuthV2 continueOnError="false" enabled="true" name="Revoke-OAuth-v20-1">
```

The following table describes attributes that are common to all policy parent elements:

| Attribute | Description | Default | Presence |
|---|---|---|---|
| `name` | The internal name of the policy. The value of the `name` attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters. Optionally, use the `<DisplayName>` element to label the policy in the management UI proxy editor with a different, natural-language name. | N/A | Required |
| `continueOnError` | Set to `false` to return an error when a policy fails. This is expected behavior for most policies. Set to `true` to have flow execution continue even after a policy fails. | false | Optional |
| `enabled` | Set to `true` to enforce the policy. Set to `false` to *turn off* the policy. The policy will not be enforced even if it remains attached to a flow. | true | Optional |
| `async` | This attribute is deprecated. | false | Deprecated |

## \<DisplayName\> element

Use in addition to the `name` attribute to label the policy in the
management UI proxy editor with a different, natural-language name.

```
<DisplayName>Policy Display Name</DisplayName>
```

| Default | N/A If you omit this element, the value of the policy's `name` attribute is used. |
| Presence | Optional |
| Type | String |
|---|---|

## \<AppId\> element

Specifies the developer app ID of the tokens to revoke. Pass either a variable that contains the
app ID or a literal app ID.

```
<AppId>appIdString</AppId>

or:

<AppId ref="request.queryparam.app_id"></AppId>
```

| Default | `request.formparam.app_id` (a x-www-form-urlencoded and specified in the request body) |
| Presence | Optional |
| Type | String |
| Valid values | Either a flow variable containing an app ID string, or a literal string. |
|---|---|

## \<Cascade\> element


If `true` and you have a traditional opaque access token, then both the
refresh token and access token will be revoked if either `<AppId>` or
`<EndUserId>` match.
If `false`,
only the access token is revoked and the refresh token is unchanged. The same behavior applies
for opaque access tokens only.

```
<Cascade>false<Cascade>
```

| Default | false |
| Presence | Optional |
| Type | Boolean |
| Valid values | `true` or `false` |
|---|---|

## \<EndUserId\> element

Specifies the app end-user ID of the token to revoke. Pass either a variable that contains the
user ID or a literal token string.

```
<EndUserId>userIdString</EndUserId>

or:

<EndUserId ref="request.queryparam.access_token"></EndUserId>
```

| Default | `request.formparam.enduser_id` (a x-www-form-urlencoded and specified in the request body) |
| Presence | Optional |
| Type | String |
| Valid values | Either a flow variable containing a user ID string, or a literal string. |
|---|---|

## \<RevokeBeforeTimestamp\> element

Revoke tokens that were issued before the timestamp. This element works with `<AppId>`
and `<EndUserId>` to let you revoke tokens before a specific time.
The default value is the time that the policy executes.

```
<RevokeBeforeTimestamp>timeStampString</RevokeBeforeTimestamp>

or:

<RevokeBeforeTimestamp ref="request.queryparam.revoke_since_timestamp"></RevokeBeforeTimestamp>
```

| Default | The timestamp that the policy is executed. |
| Presence | Optional |
| Type | 64-bit (long) integer representing the number of milliseconds ellapsed since midnight, on January 1, 1970 UTC. |
| Valid values | Either a flow variable containing a timestamp, or a literal timestamp. The timestamp cannot be in the future and cannot be before January 1, 2014. |
|---|---|

## Flow variables

The RevokeOAuthV2 policy does not set flow variables.

## Error reference

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error.
This information is important to know if you are developing fault rules to
handle faults. To learn more, see [What you need to know
about policy errors](https://docs.apigee.com/api-platform/fundamentals/what-you-need-know-about-policy-errors) and [Handling
faults](https://docs.apigee.com/api-platform/fundamentals/fault-handling).

### Runtime errors

These errors can occur when the policy executes. The error names shown below are the strings
that are assigned to the `fault.name` variable when an error occurs. See the Fault
variables section below for more details.

| Fault code | HTTP status | Cause |
|---|---|---|
| `steps.oauth.v2.InvalidFutureTimestamp` | 500 | Timestamp cannot be in the future. |
| `steps.oauth.v2.InvalidEarlyTimestamp` | 500 | Timestamp cannot be earlier than January 1, 2014. |
| `steps.oauth.v2.InvalidTimestamp` | 500 | Timestamp is invalid. |
| `steps.oauth.v2.EmptyAppAndEndUserId` | 500 | Both `AppdId` and `EndUserId` cannot be empty. |

### Deployment errors

Refer to the message reported in the UI for information about deployment errors.

### Fault variables

These variables are set when this policy triggers an error at runtime.

> [!NOTE]
> **Note:** You an use these variables to create Fault Rule conditions. For more information, see [What you need to know
> about policy errors](https://docs.apigee.com/api-platform/fundamentals/what-you-need-know-about-policy-errors).

| Variables | Where | Example |
|---|---|---|
| `fault.name="fault_name"` | <var translate="no">fault_name</var> is the name of the fault, as listed in the [Runtime errors](https://docs.apigee.com/api-platform/reference/policies/revoke-oauth-v2-policy#runtime-errors) table above. The fault name is the last part of the fault code. | `fault.name Matches "IPDeniedAccess"` |
| `oauthV2.policy_name.failed` | <var translate="no">policy_name</var> is the user-specified name of the policy that threw the fault. | `oauthV2.GetTokenInfo.failed = true` |
| `oauthV2.policy_name.fault.name` | <var translate="no">policy_name</var> is the user-specified name of the policy that threw the fault. | `oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id` |
| `oauthV2.policy_name.fault.cause` | <var translate="no">policy_name</var> is the user-specified name of the policy that threw the fault. | `oauthV2.GetTokenInfo.cause = ClientID is Invalid` |

### Example error response

```
{
   "fault":{
      "faultstring":"Timestamp is in the future.",
      "detail":{
         "errorcode":"steps.oauth.v2.InvalidFutureTimestamp"
      }
   }
}
```

### Example fault rule

```
<FaultRule name="RevokeOAuthV2 Faults">
    <Step>
        <Name>AM-InvalidTimestamp</Name>
    </Step>
    <Condition>(fault.name = "InvalidFutureTimestamp")</Condition>
</FaultRule>
```

## Related topics

- [OAuthV2 policy](https://docs.apigee.com/api-platform/reference/policies/oauthv2-policy)
- [OAuth home](https://docs.apigee.com/api-platform/security/oauth/oauth-home)
- [Customizing Tokens
  and Authorization Codes](https://docs.apigee.com/api-platform/security/oauth/customizing-access-tokens)