Square

The Square auth provider enables tools and agents to call Square APIs  on behalf of a user using OAuth 2.0 authentication.

What’s documented here

This page describes how to use and configure Square auth with Arcade.

This auth provider is used by:

• The Arcade Square MCP Server, which provides pre-built tools for interacting with Square
• Your app code that needs to call the Square API
• Or, your custom tools that need to call the Square API

Configuring Square auth

In a production environment, you will most likely want to use your own Square app credentials. This way, your users will see your application’s name requesting permission.

Before showing how to configure your Square app credentials, let’s go through the steps to create a Square app.

Create a Square app

To integrate with Square’s API, you’ll need to create an application in the Square Developer Dashboard:

For detailed instructions, refer to Square’s OAuth documentation .

Next, add the Square app to Arcade.

Configuring your own Square Auth Provider in Arcade

export SQUARE_CLIENT_ID="<your application ID>"
export SQUARE_CLIENT_SECRET="<your application secret>"

SQUARE_CLIENT_ID="<your application ID>"
SQUARE_CLIENT_SECRET="<your application secret>"

auth:
  providers:
    - id: arcade-square
      description: Square OAuth 2.0 provider
      enabled: true
      type: oauth2
      client_id: ${env:SQUARE_CLIENT_ID}
      client_secret: ${env:SQUARE_CLIENT_SECRET}
      oauth2:
        scope_delimiter: " "
        authorize_request:
          endpoint: "https://connect.squareup.com/oauth2/authorize"
          params:
            response_type: code
            client_id: "{{client_id}}"
            redirect_uri: "{{redirect_uri}}"
            scope: "{{scopes}}"
            state: "{{state}}"
        token_request:
          endpoint: "https://connect.squareup.com/oauth2/token"
          params:
            grant_type: authorization_code
            client_id: "{{client_id}}"
            client_secret: "{{client_secret}}"
            redirect_uri: "{{redirect_uri}}"
          response_content_type: application/json

When you use tools that require Square auth using your Arcade account credentials, Arcade will automatically use this Square OAuth provider. If you have multiple Square providers, see using multiple auth providers of the same type for more information.

Using Square auth in app code

Use the Square auth provider in your own agents and AI apps to get a user token for the Square API. See authorizing agents with Arcade to understand how this works.

Use client.auth.start() to get a user token for the Square API:

from arcadepy import Arcade
 
client = Arcade()  # Automatically finds the `ARCADE_API_KEY` env variable
 
user_id = "{arcade_user_id}"
 
# Start the authorization process
auth_response = client.auth.start(
    user_id=user_id,
    provider="arcade-square",
    scopes=["MERCHANT_PROFILE_READ", "PAYMENTS_READ"]
)
 
if auth_response.status != "completed":
    print("Please complete the authorization challenge in your browser:")
    print(auth_response.url)
 
# Wait for the authorization to complete
auth_response = client.auth.wait_for_completion(auth_response)
 
token = auth_response.context.token
# Do something interesting with the token...

import { Arcade } from "@arcadeai/arcadejs";
 
const client = new Arcade();
 
const userId = "{arcade_user_id}";
 
// Start the authorization process
const authResponse = await client.auth.start(
  userId,
  "arcade-square",
  ["MERCHANT_PROFILE_READ", "PAYMENTS_READ"]
);
 
if (authResponse.status !== "completed") {
  console.log("Please complete the authorization challenge in your browser:");
  console.log(authResponse.url);
}
 
// Wait for the authorization to complete
authResponse = await client.auth.waitForCompletion(authResponse);
 
const token = authResponse.context.token;
// Do something interesting with the token...

Using Square auth in custom tools

You can use the pre-built Arcade Square MCP Server to quickly build agents and AI apps that interact with Square.

If the pre-built tools in the Square MCP Server don’t meet your needs, you can author your own custom tools that interact with the Square API.

Use the OAuth2() auth class to specify that a tool requires authorization with Square. The context.authorization.token field will be automatically populated with the user’s Square token:

from typing import Annotated
 
import httpx
from arcade_tdk import ToolContext, tool
from arcade_tdk.auth import OAuth2
 
 
@tool(
    requires_auth=OAuth2(
        provider_id="arcade-square",
        scopes=["MERCHANT_PROFILE_READ"]
    )
)
async def get_merchant_info(
    context: ToolContext,
) -> Annotated[dict, "The merchant information."]:
    """
    Retrieve merchant profile information from Square.
    """
    url = "https://connect.squareup.com/v2/merchants/me"
    headers = {
        "Authorization": context.authorization.token,
        "Content-Type": "application/json",
    }
 
    async with httpx.AsyncClient() as client:
        response = await client.get(url, headers=headers)
        response.raise_for_status()
        return dict(response.json())

Available Scopes

Square supports various OAuth scopes that determine the level of access your application has:

• MERCHANT_PROFILE_READ - Read merchant profile information
• PAYMENTS_READ - Read payment information
• PAYMENTS_WRITE - Process payments
• CUSTOMERS_READ - Read customer information
• CUSTOMERS_WRITE - Create and update customers
• ORDERS_READ - Read order information
• ORDERS_WRITE - Create and update orders
• INVENTORY_READ - Read inventory information
• INVENTORY_WRITE - Update inventory

For a complete list of available scopes, refer to the Square OAuth Permissions documentation .