Token Introspection

Applies to: OAuth API

Learn how to use the OAuth API to get the scope details of an access token.

The RetrieveTokenStatus endpoint performs token introspection of an OAuth access token or an application's personal access token.

With the RetrieveTokenStatus endpoint, you can ensure that a token grants all the permissions you need without having to find the scope through trial and error by calling different Square endpoints.

The following is an example RetrieveTokenStatus request where access_token is a valid production authorization credential (see Get a personal access token).

curl https://connect.squareup.com/oauth2/token/status \
  -X POST \
  -H 'Square-Version: 2022-12-14' \
  -H 'Authorization: Bearer <access_token>’ \
  -H 'Content-Type: application/json'

The following is an example response:

{
  "scopes": [
    "PAYMENTS_READ",
    "PAYMENTS_WRITE"
  ],
  "expires_at": "2022-10-20T22:03:46Z",
  "client_id": "clientid",
  "merchant_id": "merchantId"
}

You can use the RetrieveTokenStatus endpoint to gracefully handle revoked or expired access tokens, check the scopes of different seller access tokens, and check whether an access token is valid before a nightly batch job.

Consider a scenario where your application gets a large number of requests that it handles in parallel to stay responsive. A batch of requests receives 401 errors because their access tokens have expired.

You can use the RetrieveTokenStatus endpoint to first check whether a request has a valid access token.

Consider a CLI application that runs a set of tasks to update a catalog for a coffee shop and ensures that the catalog is accurate.

You can use the RetrieveTokenStatus endpoint to first check the scope of the seller's access token and then run all the necessary tasks.

Consider a scenario where an enterprise plugin uses an access token that expires every 24 hours.

You can use the RetrieveTokenStatus endpoint to check whether the access token is valid every hour so that you can refresh the access token, if needed, in time for the next batch job.