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

POST token=tokenvalue in application/x-www-form-urlencoded format to https://login.salesforce.com/services/oauth2/revoke – the HTTP request looks like this:

    POST /services/oauth2/revoke HTTP/1.1
    Host: login.salesforce.com 
    Content-Type: application/x-www-form-urlencoded

    token=tokenvalue

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.

JSONP

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="https://login.salesforce.com/services/oauth2/revoke?token=tokenvalue&callback=myCallback">
</script>

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.

GET

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

https://login.salesforce.com/services/oauth2/revoke?token=currenttoken

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

In all cases, for Sandbox orgs, use test.salesforce.com instead of login.salesforce.com. 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 Force.com REST API Developer’s Guide Ver. 23 Winter ’12.
    - Why not ‘redirect_uri’ for GET/POST, as /services/oauth2/authorize does?

    • http://blog.superpat.com/ Pat Patterson

      Hi Masao – technically, it’s not part of the REST API, but part of the OAuth implementation, and is documented at https://na9.salesforce.com/help/doc/en/remoteaccess_revoke_token.htm. No redirect URI, because there is no user input needed – you can use GET/POST/JSONP within a page rather than loading the revoke endpoint as the page then redirecting elsewhere.

  • http://twitter.com/_drako Richard Tuttle

    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.