OAuth: Code Cookbook

Revoke OAuth Token

Respect user privacy by enabling them to revoke unwanted OAuth tokens.

Before you start Permalink Get a link to this section

To use the example code as written, you need the following:

Step 1: Add code to let users revoke access to their accounts Permalink Get a link to this section

Create a PHP file called revoke_token.php and add code to let users revoke access to their accounts. Make sure the revoke token page is in the same password-protected area as the main OAuth flow page.

<h2>Revoke Access to your Account</h2>
<p>
  Click the following button to close your account or revoke access to your Square account.
</p>

<form action="revoke_token.php" method="post">
  <input type="submit" id="submit" value="Revoke Access" />
</form>

Step 2: Revoke the OAuth token Permalink Get a link to this section

Run a cURL command to call the OAuth API and revoke the access token.

If your request is successful, RevokeToken revokes the OAuth token and you receive a 200 response.

Revoke Token
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
curl https://connect.squareupsandbox.com/oauth2/revoke \
  -X POST \
  -H 'Square-Version: 2021-05-13' \
  -H 'Authorization: Client {CLIENT_SECRET}' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "{CLIENT_ID}",
    "access_token": "{ACCESS_TOKEN}"
  }'
Try in API Explorer

Step 3 (optional): Revoke a single access token Permalink Get a link to this section

Revoke a single access token, but leave the authorization active.

Revoke Token
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
curl https://connect.squareupsandbox.com/oauth2/revoke \
  -X POST \
  -H 'Square-Version: 2021-05-13' \
  -H 'Authorization: Client {CLIENT_SECRET}' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "{CLIENT_ID}",
    "access_token": "{ACCESS_TOKEN}",
    "revoke_only_access_token": true
  }'
Try in API Explorer

Webhook notifications Permalink Get a link to this section

If you have subscribed to the oauth.authorization.revoked event and configured a webhook notification listener endpoint, your listener receives a notification whose body looks like the following example:

{
  "merchant_id": "{{MERCHANT_ID}}",
  "type": "oauth.authorization.revoked",
  "event_id": "e1d6ae37-5aa9-45a5-b525-b12caf819fdb",
  "created_at": "2020-08-14T15:51:04.246373287Z",
  "data": {
    "type": "revocation",
    "id": "415641cf-eba2-4dfa-88cc-c4be1301fdc6",
    "object": {
      "revocation": {
        "revoked_at": "2020-08-14T15:51:00.246373287Z",
        "revoker_type": "MERCHANT"
      }
    }
  }
}

A webhook notification is sent for each access token that is revoked.