Square Authentication: API Access and Security (2026)

Authentication overview

Authentication for Square APIs establishes and verifies the identity of an application or user attempting to interact with a Square seller's account. This process is fundamental for ensuring that sensitive data, such as payment information and customer records, remains protected and that only authorized operations are performed. Square provides distinct authentication mechanisms tailored for different integration scenarios, whether building a public application for multiple sellers or a private integration for a single seller's account. All API interactions with Square require a valid access token to authorize requests, which is typically passed in the Authorization header of HTTP requests. Understanding the appropriate method and managing credentials securely are critical steps in developing any Square API integration, aligning with general industry standards for API security, such as those outlined by the OAuth 2.0 authorization framework.

The chosen authentication method dictates how an application obtains and manages these access tokens. For public applications designed for multiple Square sellers, the OAuth 2.0 protocol is the standard. This allows sellers to grant specific permissions to an application without sharing their Square account credentials directly. For private applications or integrations built for a single Square seller's internal use, Personal Access Tokens provide a simpler, direct method of authentication. Both methods ensure that API requests are made on behalf of an authorized Square account and adhere to the principle of least privilege by scope-based permissions.

Supported authentication methods

Square supports two primary authentication methods for its APIs, each designed for specific use cases:

1. OAuth 2.0: This is the recommended method for applications that will be used by multiple Square sellers (public applications). OAuth 2.0 allows Square sellers to grant your application permission to access their Square account data and perform actions on their behalf, without ever sharing their actual Square login credentials with your application. The process involves an authorization flow where the seller is redirected to Square's website to approve the application's access. Upon approval, Square issues an authorization code, which your application exchanges for an access token and a refresh token. The access token is used to make API calls, and the refresh token is used to obtain new access tokens when the current one expires. Square's implementation of OAuth 2.0 is based on the RFC 6749 specification for OAuth 2.0.
2. Personal Access Tokens: These tokens are suitable for private applications or integrations built for a single Square seller's account (private applications). A Personal Access Token is a long-lived string generated directly from the Square Developer Dashboard. It grants direct access to the Square account that generated it, based on the permissions assigned to the token. Unlike OAuth 2.0, there is no interactive authorization flow. Personal Access Tokens should be treated with the same level of security as a password due to their direct access capabilities. They are ideal for backend services, scripts, or internal tools that do not require user interaction for authorization.

Authentication methods comparison

Getting your credentials

To begin integrating with Square APIs, you need to obtain the appropriate credentials from the Square Developer Dashboard. The steps vary slightly depending on whether you're creating a public OAuth application or a private integration with a Personal Access Token.

For OAuth 2.0 applications:

1. Create an Application: Log in to your Square Developer Dashboard and navigate to the "Applications" section. Click "New Application" to create a new application.
2. Configure OAuth Redirect URL: In your application settings, specify one or more "OAuth Redirect URLs." These are the URLs to which Square will redirect the seller after they grant or deny permissions to your application. This is a critical security measure to prevent phishing and ensure the authorization code is sent to your legitimate application endpoint.
3. Retrieve Application ID and Secret: Once the application is created, you will be provided with an Application ID and an Application Secret. The Application ID is public and is used to identify your application during the OAuth flow. The Application Secret is confidential and must be kept secure, as it is used to exchange the authorization code for an access token.
4. Define Scopes: Determine the necessary permissions (scopes) your application requires to interact with a seller's account. Scopes define the level of access your application requests, such as MERCHANT_PROFILE_READ for reading merchant data or PAYMENTS_WRITE for processing payments. Requesting only the necessary scopes adheres to the principle of least privilege, enhancing security. Details on available scopes are provided in the Square OAuth API overview.

For Personal Access Tokens:

1. Access Developer Dashboard: Log in to your Square Developer Dashboard.
2. Navigate to Personal Access Tokens: Go to the "Personal Access Tokens" section.
3. Create New Token: Click "New Personal Access Token."
4. Assign Permissions (Scopes): Select the specific permissions (scopes) that this token should have. Similar to OAuth, these scopes define what operations the token can perform. Choose only the permissions absolutely necessary for your integration.
5. Generate and Secure Token: Square will generate a unique Personal Access Token. This token is displayed only once. It's crucial to copy it immediately and store it securely. If lost, you will need to revoke it and generate a new one.

Authenticated request example

Once you have obtained an access token (either via OAuth 2.0 or a Personal Access Token), you can use it to make authenticated requests to Square APIs. The access token must be included in the Authorization header of your HTTP request, prefixed with Bearer. The specific API endpoint and payload will depend on the operation you intend to perform.

Example: Retrieving merchant's location data using a JavaScript (Node.js) SDK

This example demonstrates how to fetch a list of locations associated with a Square merchant account using the Node.js SDK, assuming you have an access token.

const { Client, Environment } = require('square');

// Replace with your actual access token
const accessToken = 'YOUR_ACCESS_TOKEN'; 

const squareClient = new Client({
  accessToken: accessToken,
  environment: Environment.Sandbox, // Use Environment.Production for live applications
});

const { locationsApi } = squareClient;

async function listLocations() {
  try {
    const response = await locationsApi.listLocations();
    console.log('Merchant locations:', response.result.locations);
  } catch (error) {
    console.error('Error fetching locations:', error.result);
  }
}

listLocations();

In this example:

• YOUR_ACCESS_TOKEN should be replaced with the actual access token obtained from either the OAuth flow or a Personal Access Token.
• Environment.Sandbox is used for testing purposes. For production applications, you must use Environment.Production.
• The locationsApi.listLocations() method makes an authenticated call to the Square Locations API endpoint.

Similar patterns apply across Square's various SDKs and direct HTTP requests. The key is consistently including the Authorization: Bearer [ACCESS_TOKEN] header.

Security best practices

Securely managing authentication credentials is paramount when integrating with Square APIs. Adhering to these best practices helps protect sensitive data and maintain the integrity of your application and Square seller accounts.

• Store Credentials Securely: Never hardcode API keys or access tokens directly into your application's source code. Store them in environment variables, secure configuration files, or a dedicated secret management service. For client-side applications using OAuth, ensure the Application Secret is only used on your backend server.
• Use HTTPS/TLS for All Communications: All communication with Square APIs must occur over HTTPS (TLS). This encrypts data in transit, protecting access tokens and sensitive payloads from interception. Square enforces HTTPS for all API endpoints, but it's important to ensure your application also uses it consistently. This aligns with general web security standards like those promoted by the Mozilla Developer Network's guide on TLS.
• Implement OAuth 2.0 Correctly: For public applications, strictly follow the OAuth 2.0 authorization flow. Validate redirect URLs, protect your Application Secret, and ensure state parameters are used to prevent CSRF attacks. Exchange authorization codes for tokens on your backend server, never directly from a client-side application.
• Rotate Access Tokens and Refresh Tokens: For OAuth applications, implement a mechanism to refresh access tokens using the refresh token before they expire. Store refresh tokens securely and rotate them if compromised.
• Apply Principle of Least Privilege: When generating Personal Access Tokens or requesting OAuth scopes, grant only the minimum necessary permissions for your application to function. Avoid requesting broad permissions if your application only needs to perform limited operations. This reduces the potential impact if a token is compromised.
• Monitor API Usage and Logs: Regularly monitor your application's API usage for unusual activity. Square's Developer Dashboard provides insights into API calls, which can help detect unauthorized access attempts or misuse of tokens. Implement logging for authentication failures and successful token issuance/refresh.
• Revoke Compromised Tokens: If you suspect an access token or Personal Access Token has been compromised, immediately revoke it through the Square Developer Dashboard. For OAuth applications, you can also programmatically revoke tokens using the Square API.
• Secure Your Server Environment: The security of your server where credentials are stored and API calls are made is paramount. Follow industry best practices for server security, including regular patching, firewall configuration, and access control.