Lemon Squeezy Authentication: API Keys & Webhooks (2026)

Authentication overview

Lemon Squeezy secures access to its API through the use of API keys, which function as bearer tokens for authenticating requests. This mechanism allows developers to programmatically interact with their Lemon Squeezy accounts, enabling operations such as managing products, handling subscriptions, and retrieving order information. The API is designed as a RESTful interface, facilitating standard HTTP methods for resource manipulation. For asynchronous event notifications, such as successful payments or subscription changes, Lemon Squeezy utilizes webhooks, which are secured with HMAC-SHA256 signatures to ensure data integrity and authenticity. This dual approach provides both request-response security and verifiable event-driven communication.

Integrating with Lemon Squeezy requires developers to obtain and manage their API keys securely. The platform provides SDKs in several programming languages, including PHP, Ruby, Python, and JavaScript, to streamline the authentication process and API interactions. These SDKs typically abstract the underlying HTTP request details, allowing developers to focus on application logic rather than low-level authentication headers. Understanding the lifecycle and security implications of API keys is central to building secure and reliable integrations with the Lemon Squeezy platform.

Supported authentication methods

Lemon Squeezy primarily supports API key authentication for its core API and cryptographic signatures for webhook verification. Each method serves a distinct purpose in securing different communication flows.

API Key Authentication

API keys are long, randomly generated strings that act as a secret token. When making requests to the Lemon Squeezy API, this key is included in the Authorization header as a Bearer token. This method is suitable for server-to-server communication where the API key can be securely stored and managed. Lemon Squeezy's API keys are designed to provide full access to the resources associated with your account, meaning they should be treated with the same level of security as a password. Exposure of an API key could lead to unauthorized access and manipulation of your store's data.

Webhook Signatures

Webhooks are used by Lemon Squeezy to notify your application of events occurring within your store, such as a new order or a subscription update. To ensure that these notifications are legitimate and have not been tampered with, Lemon Squeezy includes a cryptographic signature in the X-Signature header of each webhook request. Your application is responsible for verifying this signature using a shared secret. This process typically involves computing an HMAC-SHA256 hash of the webhook payload and comparing it against the received signature. Verification of webhook signatures is a critical security measure against replay attacks and spoofed requests, as detailed in general webhook security guidance like Twilio's webhook security documentation.

The following table summarizes the authentication methods:

Getting your credentials

To interact with the Lemon Squeezy API, you will need to generate an API key from your Lemon Squeezy dashboard. For webhook verification, a shared secret is provided when you configure a webhook endpoint.

Generating an API Key

1. Log in to your Lemon Squeezy account.
2. Navigate to Settings.
3. Select API from the left-hand menu.
4. Click the + New API Key button.
5. Provide a descriptive name for your API key (e.g., "My Application Integration").
6. Click Create API Key.
7. The newly generated API key will be displayed. Copy this key immediately, as it will only be shown once. If you lose it, you will need to generate a new key and update any applications using the old one.

Refer to the official Lemon Squeezy API authentication guide for the most current instructions.

Obtaining a Webhook Signing Secret

1. Log in to your Lemon Squeezy account.
2. Navigate to Settings.
3. Select Webhooks from the left-hand menu.
4. Click the + New Webhook button or edit an existing webhook.
5. When creating or editing a webhook, a "Signing Secret" will be displayed. This secret is used to generate and verify webhook signatures. Copy this secret and store it securely in your application's environment variables or configuration.
6. Save your webhook configuration.

The Lemon Squeezy Webhooks documentation provides further details on setting up and verifying webhooks.

Authenticated request example

This example demonstrates how to make an authenticated request to the Lemon Squeezy API using an API key to retrieve a list of products. This example uses curl, but the principle applies across all supported SDKs and programming languages.

curl -X GET \
  'https://api.lemonsqueezy.com/v1/products' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer YOUR_API_KEY'

In this example:

• YOUR_API_KEY should be replaced with the actual API key generated from your Lemon Squeezy dashboard.
• The -H 'Authorization: Bearer YOUR_API_KEY' header is where the API key is passed. The Bearer prefix is standard for this type of token authentication, as outlined in RFC 6750 for Bearer Token Usage.
• The Accept and Content-Type headers specify that the API expects and will return JSON API compliant data.

For server-side webhook verification, the process involves receiving a POST request from Lemon Squeezy, extracting the X-Signature header, and computing your own signature based on the request body and your stored webhook secret. If the computed signature matches the received signature, the webhook is considered valid.

Security best practices

Adhering to security best practices is crucial when integrating with any API, especially one that handles sensitive payment and customer data. For Lemon Squeezy authentication, consider the following:

API Key Management

• Environment Variables: Never hardcode API keys directly into your source code. Instead, store them as environment variables on your server or in a secure configuration management system. This prevents keys from being exposed in version control systems.
• Access Control: Restrict access to API keys to only the necessary personnel and systems. Implement role-based access control (RBAC) to ensure that only authorized individuals can view or modify these credentials.
• Rotation: Regularly rotate your API keys. While Lemon Squeezy does not enforce automatic rotation, implementing a manual rotation schedule (e.g., every 90 days) can mitigate the risk if a key is compromised without your knowledge.
• Least Privilege: If Lemon Squeezy introduces scoped API keys in the future, always generate keys with the minimum necessary permissions required for the application's functionality.
• Monitoring: Monitor API usage logs for unusual activity that might indicate a compromised key.

Webhook Security

• Verify Signatures: Always verify the X-Signature header on every incoming webhook request. This is the primary defense against spoofed or tampered webhook events. Implement a robust verification logic in your webhook endpoint.
• Idempotency: Design your webhook handlers to be idempotent. This means that processing the same webhook event multiple times should not cause unintended side effects. While signature verification helps prevent unauthorized duplicates, network issues can sometimes lead to legitimate duplicate deliveries.
• HTTPS Endpoints: Ensure your webhook endpoint uses HTTPS. This encrypts the webhook payload in transit, protecting sensitive data from eavesdropping.
• Secret Management: Store your webhook signing secret securely, similar to API keys, using environment variables or a secrets manager.
• Timestamps: While not explicitly mentioned in Lemon Squeezy's webhook docs, many platforms include timestamps in webhook headers to help mitigate replay attacks. If available, incorporate timestamp verification to ensure webhooks are processed within a reasonable time window.

General Security Practices

• Secure Development Lifecycle: Incorporate security considerations throughout your development process, from design to deployment and maintenance.
• Error Handling: Implement robust error handling without exposing sensitive information in error messages or logs.
• Input Validation: Always validate and sanitize any input received from external sources, including webhook payloads, to prevent injection attacks and other vulnerabilities.
• Dependencies: Keep all project dependencies and SDKs updated to their latest versions to benefit from security patches.