Stripe Connect Authentication: API Keys and OAuth 2.0 (2026)

Authentication overview

Stripe Connect, a platform for multi-sided marketplaces and businesses facilitating payments between multiple parties, relies on robust authentication mechanisms to secure interactions between platforms, connected accounts, and the Stripe API. The authentication framework ensures that only authorized entities can perform actions, such as creating charges, managing payouts, or accessing sensitive financial data on behalf of users. Stripe Connect differentiates between authentication for the platform itself and authentication for connected accounts, which are external users or businesses integrated into the platform.

Platform authentication primarily involves API keys, which grant the platform direct access to the Stripe API to manage its own resources and interact with connected accounts. For actions performed on behalf of connected accounts, Stripe Connect leverages OAuth 2.0, an industry-standard protocol for delegated authorization. This allows platforms to obtain explicit permission from users to perform specific actions without directly handling their credentials. The combination of API keys and OAuth 2.0 provides a secure and flexible system for managing diverse payment flows and user interactions within the Stripe Connect ecosystem.

Understanding the appropriate authentication method for each scenario is critical for secure and compliant integration. Improper handling of credentials or authorization flows can lead to security vulnerabilities, unauthorized access, or non-compliance with regulatory standards like PCI DSS Level 1.

Supported authentication methods

Stripe Connect primarily supports two authentication methods: API keys for direct platform access and OAuth 2.0 for delegated authorization to connected accounts.

API Keys

API keys are used by the platform to authenticate requests made directly to the Stripe API. These keys are generated and managed within the Stripe Dashboard. There are several types of API keys, each with specific permissions and use cases:

• Publishable API Keys: These keys are designed for use in client-side code, such as JavaScript on a website. They identify your account but do not grant access to sensitive operations, making them safe to expose publicly. Publishable keys are typically used for client-side tokenization of payment information before it is sent to your server.
• Secret API Keys: These keys grant full access to your Stripe account's API and must be kept confidential. They are used for server-side operations, such as creating charges, issuing refunds, or retrieving sensitive customer data. Secret keys should never be exposed in client-side code or publicly accessible environments.
• Restricted API Keys: These keys provide granular control over permissions. Platforms can create restricted keys with specific read/write access to certain API resources, limiting the potential impact if a key is compromised. This method is useful for granting access to third-party services or internal tools with limited functionality requirements. More details on restricted keys are available in the Stripe API keys documentation.

OAuth 2.0

OAuth 2.0 is the standard protocol used by Stripe Connect to allow platforms to act on behalf of connected accounts. This process involves redirecting users to Stripe's authorization page, where they grant permission to the platform. Upon successful authorization, Stripe provides the platform with an access token, which can then be used to make API calls on behalf of that specific connected account. Stripe Connect implements the Authorization Code Grant flow, which is suitable for server-side applications.

The OAuth 2.0 flow typically involves these steps:

1. The platform redirects the user (connected account) to Stripe's OAuth authorization URL.
2. The user logs into their Stripe account (if not already logged in) and reviews the permissions requested by the platform.
3. The user grants permission to the platform.
4. Stripe redirects the user back to a pre-configured redirect_uri on the platform's server, including an authorization code.
5. The platform's server exchanges this authorization code for an access token and a refresh token by making a server-to-server request to Stripe's token endpoint, authenticated with the platform's secret API key.
6. The access token is then used to make API requests on behalf of the connected account. Refresh tokens are used to obtain new access tokens when the current one expires, without requiring the user to re-authorize.

For a comprehensive guide on implementing OAuth for connected accounts, refer to the Stripe Connect OAuth documentation.

Getting your credentials

Platforms can obtain and manage their API keys directly from the Stripe Dashboard. After logging in, navigate to the Developers > API keys section. Here, you can find your publishable and secret API keys. For security, secret keys are only shown once upon creation and should be stored securely immediately.

To implement OAuth 2.0 for connected accounts, you will need to configure your platform's OAuth settings in the Stripe Dashboard. This includes setting up your redirect_uri, which is the URL Stripe will redirect users to after they authorize your platform. You can also customize the branding of the Stripe Connect onboarding flow to match your platform's look and feel, enhancing the user experience during the authorization process. The Stripe Dashboard settings for Connect also allow for managing webhook endpoints and other integration configurations.

It is crucial to differentiate between your test and live API keys. Stripe provides separate key sets for development and production environments, allowing you to test your integration thoroughly without affecting live transactions. Always ensure you are using the correct keys for the respective environment.

Authenticated request example

When making API requests using a secret API key, it is typically included in the HTTP Authorization header as a Bearer token. For requests made on behalf of a connected account using an OAuth access token, the Authorization header is also used, but an additional Stripe-Account header is required to specify which connected account the action pertains to.

Server-side API Key Authentication Example (Python)

This Python example demonstrates creating a charge using a platform's secret API key. The key is set as the global API key for the Stripe library.

import stripe

# Set your secret API key
stripe.api_key = "sk_live_YOUR_SECRET_KEY"

try:
    charge = stripe.Charge.create(
        amount=2000, # $20.00
        currency="usd",
        source="tok_visa", # obtained with Stripe.js
        description="Charge for test product"
    )
    print(f"Charge successful: {charge.id}")
except stripe.error.StripeError as e:
    print(f"Error creating charge: {e}")

OAuth Access Token Authentication Example (Node.js)

This Node.js example shows how to make an API call on behalf of a connected account using an OAuth access token. The Stripe-Account header specifies the connected account ID.

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

const connectedAccountId = 'acct_1234567890abcdefg'; // ID of the connected account
const accessToken = 'sk_live_YOUR_CONNECTED_ACCOUNT_ACCESS_TOKEN'; // OAuth access token for the connected account

async function createChargeOnBehalf() {
  try {
    const charge = await stripe.charges.create({
      amount: 1500, // $15.00
      currency: 'usd',
      source: 'tok_visa', // obtained with Stripe.js from the connected account's client
      description: 'Charge for service on behalf of connected account',
    }, {
      stripeAccount: connectedAccountId // Specifies the connected account
    });
    console.log(`Charge successful for connected account: ${charge.id}`);
  } catch (error) {
    console.error(`Error creating charge for connected account: ${error.message}`);
  }
}

createChargeOnBehalf();

The stripeAccount parameter in the Node.js example is equivalent to setting the Stripe-Account header. This is a crucial distinction for making API calls on behalf of connected accounts, ensuring that the transaction is correctly attributed and processed through the specified account.

Security best practices

Adhering to security best practices is essential when integrating with Stripe Connect to protect sensitive data and maintain compliance.

• Keep Secret API Keys Confidential: Never expose your secret API keys in client-side code, public repositories, or unsecured environments. Store them as environment variables or in a secure secrets management service. Rotate them regularly, especially if there's any suspicion of compromise.
• Use Restricted API Keys: For integrations that only require limited access to your Stripe account, create and use restricted API keys. This minimizes the blast radius in case a key is compromised, as it will only have permissions to the specific resources you've allowed.
• Secure OAuth Redirect URIs: Ensure your OAuth redirect_uri is secured with HTTPS and configured to accept redirects only to specific, controlled endpoints. This prevents malicious actors from intercepting authorization codes.
• Validate OAuth State Parameter: Implement the state parameter in your OAuth 2.0 flow to prevent Cross-Site Request Forgery (CSRF) attacks. The state parameter should be a unique, unguessable value generated by your application and verified upon redirection from Stripe. This is a standard security measure for OAuth implementations, as detailed in the OAuth 2.0 RFC Section 10.12.
• Securely Store Access and Refresh Tokens: Store OAuth access and refresh tokens securely on your server. Avoid storing them in client-side storage like local storage or cookies, where they can be vulnerable to XSS attacks. Encrypt tokens at rest and ensure proper access controls are in place.
• Implement Webhook Signature Verification: Stripe sends webhook events to your platform to notify you of various occurrences. Always verify the signature of incoming webhooks to ensure they genuinely originate from Stripe and have not been tampered with. This prevents spoofing attacks and ensures the integrity of event data. The Stripe webhook security guide provides detailed instructions on how to implement signature verification.
• Principle of Least Privilege: Grant only the necessary permissions to API keys and connected accounts. Regularly review and adjust permissions as your integration evolves.
• PCI DSS Compliance: If your platform handles raw card data, ensure your infrastructure and processes comply with PCI DSS (Payment Card Industry Data Security Standard). Stripe's own infrastructure is PCI DSS Level 1 compliant, but your platform's handling of sensitive data also needs to adhere to these standards. Using Stripe.js for client-side tokenization helps minimize your PCI compliance scope.
• Regular Security Audits: Conduct regular security audits and penetration testing of your platform to identify and address potential vulnerabilities.