Stripe Radar Authentication: API Keys & Webhook Security

Authentication overview

Stripe Radar, an integral part of the Stripe platform for fraud prevention, relies on Stripe's standard authentication mechanisms to secure access to its functionalities. This includes configuring fraud rules, reviewing risk scores, and managing disputes. The primary method for authenticating API requests to Stripe Radar is through API keys, which are used to identify and authorize applications interacting with the Stripe API. For events originating from Stripe, such as notifications about potential fraud or chargebacks, webhook signing is employed to verify the authenticity and integrity of the received data.

Proper authentication ensures that only authorized users and applications can perform actions or access sensitive data related to fraud detection and prevention. Adhering to security best practices for API key management and webhook verification is crucial for maintaining the security posture of any integration with Stripe Radar.

Supported authentication methods

Stripe Radar leverages two main authentication and verification methods:

1. API Keys: For programmatic access to the Stripe API, including Radar-specific endpoints.
2. Webhook Signing: For verifying the authenticity of events sent by Stripe to your application.

API Keys

Stripe uses two types of API keys for authentication:

• Publishable Keys: These keys are designed for use in client-side code (e.g., JavaScript on a website or mobile app). They identify your account but do not grant access to sensitive operations, making them safe to embed publicly. Publishable keys are typically prefixed with pk_live_ or pk_test_.
• Secret Keys: These keys grant extensive access to your Stripe account, including the ability to create charges, manage subscriptions, and interact with all Stripe Radar features. Secret keys must be kept confidential and should only be used on your server-side code. They are prefixed with sk_live_ or sk_test_.

When making API requests, your secret key should be passed in the Authorization header as a Bearer token. For example, Authorization: Bearer sk_live_your_secret_key. Stripe's official SDKs handle this automatically when initialized with your secret key, simplifying the authentication process for developers using Stripe Radar's API.

Webhook Signing

Webhooks are a critical component for receiving real-time notifications from Stripe about events related to your account, including those generated by Stripe Radar. To ensure the integrity and authenticity of these events, Stripe signs each webhook event with a unique secret. Your application should verify this signature to confirm that the event originated from Stripe and has not been tampered with. This process helps protect against spoofed events and replay attacks.

The signature is included in the Stripe-Signature header of each webhook request. This header contains a timestamp and one or more signatures. Stripe recommends using Stripe's official libraries to verify signatures, as they handle the cryptographic operations and timing attack protections automatically.

Authentication Methods Overview Table

Getting your credentials

All necessary credentials for Stripe Radar authentication are managed within the Stripe Dashboard. To access your API keys and webhook signing secrets:

1. Log in to your Stripe Dashboard: Navigate to the Stripe Dashboard.
2. Access API Keys: Go to Developers > API keys. Here you will find your publishable and secret keys. You can also generate new secret keys or revoke existing ones if compromised. Stripe provides separate keys for test and live modes to facilitate development and testing without affecting live transactions.
3. Access Webhook Secrets: Go to Developers > Webhooks. Select a specific webhook endpoint or create a new one. Each endpoint will have a unique 'Signing secret' which you will use to verify incoming webhook events. If you need to rotate a secret, you can do so from this section.

It is recommended to use distinct webhook endpoints and secrets for different environments (e.g., development, staging, production) to isolate potential issues and enhance security.

Authenticated request example

The following example demonstrates how to make an authenticated API request to Stripe Radar using a secret API key with the Node.js SDK. This example retrieves a list of early fraud warnings associated with your account, which is a feature of Stripe Radar for Fraud Teams.

const stripe = require('stripe')('sk_live_YOUR_SECRET_KEY');

async function getEarlyFraudWarnings() {
  try {
    const earlyFraudWarnings = await stripe.radar.earlyFraudWarnings.list({
      limit: 3
    });
    console.log('Early Fraud Warnings:', earlyFraudWarnings.data);
  } catch (error) {
    console.error('Error fetching early fraud warnings:', error);
  }
}

getEarlyFraudWarnings();

In this example:

• sk_live_YOUR_SECRET_KEY must be replaced with your actual live secret key.
• The stripe object is initialized with the secret key, which the SDK then uses to automatically include the appropriate Authorization header in all subsequent API requests.
• The request targets the radar.earlyFraudWarnings.list endpoint, demonstrating interaction with Stripe Radar specific API features.

Security best practices

Securing your Stripe Radar integration is paramount to effective fraud prevention and data protection. Adhere to these best practices:

• Keep Secret Keys Confidential: Never expose your secret API keys in client-side code, public repositories, or unsecured environments. Store them as environment variables or using a secure secret management service. Rotate your secret keys regularly, especially if there's any suspicion of compromise.
• Use Environment-Specific Keys: Utilize separate API keys for your development, staging, and production environments. This prevents accidental changes to your live data and isolates potential security incidents. Developers can learn more about environment variables for secure key storage.
• Implement Webhook Signature Verification: Always verify webhook signatures. This is the only way to guarantee that incoming events are legitimate and have not been tampered with. Use Stripe's official SDKs for robust verification.
• Secure Webhook Endpoints: Ensure your webhook endpoints are served over HTTPS and are protected from unauthorized access. Consider using a dedicated service or reverse proxy (like Nginx or Apache) to manage incoming requests securely.
• Least Privilege Principle: If you use restricted API keys (available for some Stripe accounts), grant only the minimum necessary permissions required for each application or service. This limits the blast radius in case a key is compromised.
• Monitor API Activity: Regularly review your Stripe Dashboard logs for suspicious API activity, including unusual request volumes or failed authentication attempts.
• Error Handling and Logging: Implement robust error handling for authentication failures and log relevant details (without exposing sensitive information) to aid in debugging and security audits.
• Stay Updated: Keep your Stripe SDKs and any related libraries updated to benefit from the latest security patches and features. Stripe regularly releases updates that can include security enhancements.