Square

Overview

Connect your users to Square for payment processing, inventory management, order tracking, and customer data.

Property	Value
Provider ID	square
Category	Payments
PKCE	Not supported
Token refresh	Automatic
Environments	Production and Sandbox
Redirect URI	Shown in Developer Portal

Step 1: Create a Square OAuth App

Go to the Square Developer Portal

Navigate to developer.squareup.com/apps and sign in.

Create a new application

Click Create your first application (or + to add another), enter the app name, and click Save.

Configure the redirect URI

Under OAuth, add the Alter callback URL from the Developer Portal to the Redirect URL field.

Get credentials

Copy the Application ID (Client ID) and Application Secret (Client Secret) from the Credentials tab.

Warning

Never share the application Secret publicly. Store it securely and only enter it in the Alter Vault Developer Portal.

Step 2: Add to Alter Vault

Open the Developer Portal

Go to portal.alterauth.com and navigate to the application.

Add Square provider

Go to OAuth Providers > Add Provider > Square.

Enter credentials

• Client ID: Paste your Square Application ID
• Client Secret: Paste your Square Application Secret

Select scopes

Choose the scopes the application needs.

Save

Click Save. The provider is now active.

Available Scopes

Scope	Description
MERCHANT_PROFILE_READ	Read merchant profile information
PAYMENTS_READ	Read payment records
PAYMENTS_WRITE	Create and update payments
ORDERS_READ	Read order records
ORDERS_WRITE	Create and update orders
ITEMS_READ	Read catalog item records
ITEMS_WRITE	Create and update catalog items
CUSTOMERS_READ	Read customer records
CUSTOMERS_WRITE	Create and update customer records

Notes

• Square has no scope selection in its Developer Console — the scopes selected in Alter are requested in the authorization URL when a user connects the app.
• Square scopes use SCREAMING_SNAKE_CASE (e.g. PAYMENTS_READ).
• Square access tokens expire after 30 days; Alter refreshes them automatically.
• Square’s sandbox is a separate OAuth deployment with its own Application ID and secret. Select the Sandbox environment in Alter (the Environment selector on the configuration form, or --environment sandbox on the CLI) when entering sandbox credentials; a sandbox credential is rejected at the production authorize endpoint.
• Production authorization requests carry session=false, so a seller who manages several Square accounts under one login is asked to sign in and pick the account being connected. The sandbox ignores this parameter.
• See the Square OAuth API documentation for more details.

Policy-cataloged operations

Alter policy rules can target these attested operations and families for operation-level and parameter-aware controls.

Operation ID	Families	Method	Provider path
CreatePayment	payment	POST	/v2/payments
GetPayment	read	GET	/v2/payments/{payment_id}
CancelPayment	payment	POST	/v2/payments/{payment_id}/cancel
CompletePayment	payment	POST	/v2/payments/{payment_id}/complete
RefundPayment	payment	POST	/v2/refunds
GetPaymentRefund	read	GET	/v2/refunds/{refund_id}
ListPaymentRefunds	read	GET	/v2/refunds
CreateOrder	write	POST	/v2/orders
SearchOrders	read	POST	/v2/orders/search
PayOrder	payment	POST	/v2/orders/{order_id}/pay
CreateInvoice	write	POST	/v2/invoices
ListInvoices	read	GET	/v2/invoices
UpdateInvoice	write	PUT	/v2/invoices/{invoice_id}
PublishInvoice	send	POST	/v2/invoices/{invoice_id}/publish
CancelInvoice	write	POST	/v2/invoices/{invoice_id}/cancel
DeleteInvoice	delete	DELETE	/v2/invoices/{invoice_id}
CreateCustomer	write	POST	/v2/customers
ListCustomers	read	GET	/v2/customers
SearchCustomers	read	POST	/v2/customers/search
DeleteCustomer	delete	DELETE	/v2/customers/{customer_id}
ListLocations	read	GET	/v2/locations
ListCatalog	read	GET	/v2/catalog/list
UpsertCatalogObject	write	POST	/v2/catalog/object
DeleteCatalogObject	delete	DELETE	/v2/catalog/object/{object_id}
RetrieveInventoryCount	read	GET	/v2/inventory/{catalog_object_id}
BatchRetrieveInventoryCounts	read	POST	/v2/inventory/counts/batch-retrieve