Authentication overview

Authentication for Square APIs establishes trust and verifies the identity of applications making requests, ensuring that only authorized entities can access and manipulate sensitive business data, such as payment information, catalog items, and customer profiles. Square's approach to authentication is designed to support various integration scenarios, from simple server-side applications making direct API calls to complex third-party applications needing permission to act on behalf of Square sellers. This system differentiates between personal access tokens for developers managing their own accounts and OAuth 2.0 for external applications requiring seller authorization.

The choice of authentication method depends on the application's nature and its interaction model with Square. For applications that operate solely within a developer's own Square account, a personal access token is typically sufficient. In contrast, applications designed to be used by multiple Square sellers must implement OAuth 2.0. This standard protocol enables sellers to grant limited, revocable access to their Square data without sharing their login credentials. Understanding these distinctions is crucial for securely integrating with the Square API ecosystem.

Supported authentication methods

Square primarily supports two main authentication methods for accessing its APIs:

  1. API Access Tokens (Personal Access Tokens): These are long-lived tokens generated from the Square Developer Dashboard. They grant direct access to the developer's own Square account and are suitable for server-to-server applications, backend services, or scripts that directly manage a single Square seller's data. They should be treated as sensitive credentials, similar to passwords, and stored securely.
  2. OAuth 2.0: This is an industry-standard protocol for authorization that allows third-party applications to obtain limited access to a user's resources on an HTTP service, in this case, a Square seller's account, without exposing the user's credentials. OAuth 2.0 is essential for applications that aim to serve multiple Square sellers. It involves a multi-step flow where the seller grants permission to the application, and the application receives an access token and a refresh token.

The following table summarizes Square's supported authentication methods:

Method When to Use Security Level
API Access Token (Personal Access Token) For applications accessing your own Square account (e.g., internal tools, specific backend services). High, assumes token is stored securely and scope is managed. Risk increases if exposed.
OAuth 2.0 For applications serving multiple Square sellers, requiring granular, revocable access to seller accounts. Very High, utilizes token expiration, refresh tokens, and explicit user consent for scope.

For applications that handle sensitive payment card data, Square's APIs utilize Payment Card Industry Data Security Standard (PCI DSS) compliant security measures. While Square itself maintains PCI DSS Level 1 compliance, developers are responsible for ensuring their applications also adhere to relevant security standards, particularly when handling cardholder data directly or integrating with payment forms.

Getting your credentials

To begin authenticating with Square APIs, you need to acquire the appropriate credentials from the Square Developer Dashboard. The process differs slightly based on whether you are developing a personal integration or a multi-seller application.

For Personal Access Tokens (API Access Tokens)

  1. Access the Developer Dashboard: Log in to your Square Developer Dashboard.
  2. Select an Application: Choose an existing application or create a new one. Even for personal integrations, Square organizes API access under an 'application' context.
  3. Generate Token: Navigate to the 'Credentials' section for your chosen application. You will find options to generate a new Personal Access Token.
  4. Copy and Store Securely: Once generated, the token will be displayed only once. Copy it immediately and store it in a secure location, such as an environment variable or a secrets management service. Do not hardcode it directly into your application's source code.

For OAuth 2.0 (Multi-Seller Applications)

OAuth 2.0 requires more setup as it involves application registration and configuration of redirect URLs.

  1. Create an Application: In the Square Developer Dashboard, create a new application.
  2. Obtain Application ID and Secret: Under the 'Credentials' section of your application, you will find your Application ID (also known as Client ID) and Application Secret. These are vital for initiating the OAuth flow.
  3. Configure Redirect URL(s): In the same 'Credentials' section, add and verify your application's Redirect URL(s). These are the URLs where Square will redirect the seller after they grant or deny permissions. This step is critical for security and proper functioning of the OAuth flow, as specified by the OAuth 2.0 specification.
  4. Define Permissions (Scopes): Determine the necessary permissions (scopes) your application needs to access seller data. Limiting scopes to only what is required adheres to the principle of least privilege and enhances security. Examples include PAYMENTS_READ, CUSTOMERS_WRITE, or ITEMS_READ.
  5. Implement OAuth Flow: Your application will need to initiate the OAuth flow, which involves directing the seller to Square's authorization page, handling the callback at your redirect URL, and exchanging the authorization code for an access token and refresh token.
  6. Store Tokens Securely: Access tokens (and refresh tokens) obtained via OAuth must be stored securely, typically associated with the corresponding seller's account in your application's database.

Square provides both a sandbox environment for testing and a production environment. Ensure you are generating credentials for the correct environment during development and deployment.

Authenticated request example

After obtaining an access token, you include it in the Authorization header of your API requests. The token is prefixed with Bearer. Here's an example using cURL to list orders, demonstrating how an access token is passed:

curl -X GET \
  'https://connect.squareup.com/v2/orders' \
  -H 'Square-Version: 2024-05-29' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Replace YOUR_ACCESS_TOKEN with your actual personal access token or an OAuth access token. The Square-Version header specifies the API version your application is designed to work with, ensuring consistent behavior even as Square updates its APIs. Square's API reference documentation provides specific examples for each endpoint and supported SDK.

Security best practices

Securing your Square API integrations is critical to protect sensitive business and customer data. Adhere to these best practices:

  • Token Storage: Never hardcode API access tokens directly into your application's source code. Store them in secure environment variables, a secrets management service (e.g., AWS Secrets Manager, Google Secret Manager), or a protected configuration file that is not committed to version control.
  • HTTPS/TLS: Always use HTTPS (TLS) for all API communications. Square's APIs explicitly enforce this, but it's a fundamental security principle for any web-based interaction to prevent eavesdropping and data tampering.
  • Principle of Least Privilege: When configuring OAuth scopes or generating personal access tokens, grant only the minimum necessary permissions for your application to function. Avoid giving broad access if only specific functionalities are required. Review and adjust permissions regularly.
  • Token Expiration and Refresh: For OAuth-based integrations, properly handle access token expiration. Access tokens have a limited lifespan. Use the refresh token (which has a longer lifespan) to obtain new access tokens without requiring the user to re-authorize your application. Implement robust error handling for expired or invalid tokens.
  • Secure Redirect URLs: For OAuth, configure precise and secure Redirect URLs. Use https and avoid wildcard domains if possible. Ensure these URLs are under your control and properly validate incoming requests.
  • Input Validation and Sanitization: Any data sent to Square APIs should be thoroughly validated and sanitized on your application's side to prevent injection attacks or malformed requests that could lead to security vulnerabilities.
  • Logging and Monitoring: Implement comprehensive logging for API requests and responses, especially for authentication failures. Monitor these logs for suspicious activity, such as repeated failed authentication attempts, which could indicate a brute-force attack.
  • Error Handling: Design your application to gracefully handle API errors, including authentication failures. Avoid exposing sensitive error details to end-users.
  • Regular Audits: Periodically audit your application's security posture and review your Square API integration for potential vulnerabilities. Stay informed about Square's security announcements and API updates.
  • SDK Usage: Utilize Square's official SDKs when possible. These SDKs are designed to handle many of the underlying security complexities and best practices, such as proper header formatting and error handling, making your integration more secure and reliable. Square offers SDKs for Java, PHP, Python, Ruby, C#, and Node.js.