Revoking OAuth 2.0 Access Tokens and Refresh Tokens

Among the new OAuth 2.0 features that were introduced in Winter ’12, one that is documented, but easy to overlook is revoke. This new endpoint allows you to revoke either an access token (the short-lived session token issued by OAuth) or a refresh token (the long-lived persistent token), and is super easy to use. Revoking an access token is analogous to simply logging out, but revoking a refresh token terminates an app’s authorization to call APIs on behalf of the user and revokes all outstanding access tokens issued against that refresh token. Powerful stuff!

There are three variants:


POST token=tokenvalue in application/x-www-form-urlencoded format to – the HTTP request looks like this:

    POST /services/oauth2/revoke HTTP/1.1
    Content-Type: application/x-www-form-urlencoded


You’ll receive a 200 status code if it worked out, with 400 for an error, the error detail (unsupported_token_type or invalid_token) in the body of the response.


Ideal for use from JavaScript in the browser, the JSONP variant returns a response as a callback that will be executed in the browser. Your page should contain a script statement such as

<script type="text/javascript" src="">

The browser will retrieve and execute the script content from the supplied URL, invoking your callback with the result of the revocation – an empty object, {}, for success or an error code, e.g. {"error":"invalid_token"}, for failure.


To revoke a token via a ‘blind GET’, just GET the revoke endpoint with the token as a query param:

As in the POST case, 200 indicate success, 400 failure.

In all cases, for Sandbox orgs, use instead of Also, note that, currently, only tokens issued by OAuth can be revoked in this way; an attempt to revoke a session ID issued by SOAP login() or as a sid cookie will fail. A future release will allow all tokens to be revoked via the OAuth 2.0 endpoint, regardless of their issuing mechanism.

Bookmark the permalink. Trackbacks are closed, but you can post a comment.
  • Masao Uebayashi

    – This is not documented in REST API Developer’s Guide Ver. 23 Winter ’12.
    – Why not ‘redirect_uri’ for GET/POST, as /services/oauth2/authorize does?

  • Is there a way to list the tokens a user has available to them? Use case is a user integration system that automatically revokes all access to apps like Chatter desktop/iphone/android etc. We currently inactivate their user which works most of the time, but occasionally see some users improperly deactivated and would prefer to revoke access at end of employment.