OAuth

  • Authorize

  • Revoke token

  • Obtain token

  • Retrieve token status

  • Webhooks

  • oauth.authorization.revoked

Development
  • Guides
  • API Reference
  • API Explorer
  • SDKs
  • Sample apps
  • System status
Support
  • Developer forums
  • Developer blog
  • YouTube
  • X
More
  • Square Home
  • Square Developer
  • App Marketplace
  • Partner with Square
  • Solutions Partner Program
  • Pricing
  • Sales

© 2026 Square, Inc.

  • Developer terms of service
  • Developer Integration and Marketing Agreement
  • Privacy policy
  • Partnerships
  • Sign In
  • Sign In

<- OAuth API

OAuth API

All versions ->

Retrieve token status

POST

 /oauth2/token/status

Returns information about an OAuth access token or an application’s personal access token.

Add the access token to the Authorization header of the request.

Important: The Authorization header you provide to this endpoint must have the following format:

Authorization: Bearer ACCESS_TOKEN

where ACCESS_TOKEN is a valid production authorization credential.

If the access token is expired or not a valid access token, the endpoint returns an UNAUTHORIZED error.

Guide

Token Introspection

Try in API Explorer
Link to section

Response fields

Link to section

scopes

string [ ]

The list of scopes associated with an access token.

Link to section

expires_at

string

The date and time when the access_token expires, in RFC 3339 format. Empty if the token never expires.

Link to section

client_id

string

The Square-issued application ID associated with the access token. This is the same application ID used to obtain the token.

Max Length
191
Link to section

merchant_id

string

The ID of the authorizing merchant's business.

Min Length
8
Max Length
191
Link to section

errors

Any errors that occurred during the request.

Link to section

Examples

All versions ->

POST /oauth2/token/status
curl https://connect.squareup.com/oauth2/token/status \ -X POST \ -H 'Square-Version: 2026-11-18' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json'

Response JSON

{ "scopes": [ "PAYMENTS_READ", "PAYMENTS_WRITE" ], "expires_at": "2022-10-14T14:44:00Z", "client_id": "CLIENT_ID", "merchant_id": "MERCHANT_ID" }