— No Results

    Authentication with Connect

    Learn how to authenticate as your users when using Connect, so you can perform any API actions on their behalf.

    There are two ways of authenticating requests when using the Stripe API on behalf of a connected account:

    You should use the Stripe-Account header method when possible: it’s easier and more secure. The second approach is supported for legacy compatibility, but generally shouldn’t be used in new applications. Both approaches require that you store the connected account’s information—ID or API keys–when connecting the account to your platform.

    Authentication via the Stripe-Account header

    The first, preferred, authentication option is to use your—the platform account’s—secret key and pass a Stripe-Account header identifying the connected account for which the request is being made. This curl request performs a refund of a charge on behalf of a connected account:

    curl https://api.stripe.com/v1/charges/{{CHARGE_ID}}/refunds \
  -u {{PLATFORM_SECRET_KEY}}: \
  -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}" \
  -d amount=1000

    The Stripe-Account header authentication approach is implied in any API request that includes the Stripe account ID in the URL:

    curl https://api.stripe.com/v1/accounts/{{CONNECTED_STRIPE_ACCOUNT_ID}} \
  -u {{PLATFORM_SECRET_KEY}}:

    All of Stripe’s libraries support this style of authentication on a per-request basis:

    Stripe.api_key = "{{PLATFORM_SECRET_KEY}}"
Stripe::Customer.create(
  {email: 'person@example.edu'},
  {stripe_account: '{{CONNECTED_STRIPE_ACCOUNT_ID}}'}
)

# Fetching an account just needs the ID as a parameter
Stripe::Account.retrieve('{{CONNECTED_STRIPE_ACCOUNT_ID}}')

    stripe.api_key = "{{PLATFORM_SECRET_KEY}}"
stripe.Customer.create(
  email="person@example.edu",
  stripe_account="{{CONNECTED_STRIPE_ACCOUNT_ID}}"
)

# Fetching an account just needs the ID as a parameter
stripe.Account.retrieve("{{CONNECTED_STRIPE_ACCOUNT_ID}}")

    \Stripe\Stripe::setApiKey("{{PLATFORM_SECRET_KEY}}");
\Stripe\Customer::create(
  ["email" => "person@example.edu"],
  ["stripe_account" => "{{CONNECTED_STRIPE_ACCOUNT_ID}}"]
);

// Fetching an account just needs the ID as a parameter
\Stripe\Account::retrieve("{{CONNECTED_STRIPE_ACCOUNT_ID}}");

    Stripe.apiKey = "{{PLATFORM_SECRET_KEY}}";
RequestOptions requestOptions = RequestOptions.builder().setStripeAccount("{{CONNECTED_STRIPE_ACCOUNT_ID}}").build();

Map<String, Object> params = new HashMap<String, Object>();
params.put("email", "person@example.edu");

Customer.create(params, requestOptions);

// Fetching an account just needs the ID as a parameter
Account.retrieve("{{CONNECTED_STRIPE_ACCOUNT_ID}}");

    const stripe = require('stripe')('{{PLATFORM_SECRET_KEY}}');
stripe.customers.create(
  {email: 'person@example.edu'},
  {stripe_account: '{{CONNECTED_STRIPE_ACCOUNT_ID}}'}
);

// Fetching an account just needs the ID as a parameter
stripe.accounts.retrieve('{{CONNECTED_STRIPE_ACCOUNT_ID}}');

    stripe.Key = "{{PLATFORM_SECRET_KEY}}"
params := &stripe.CustomerParams{
  Email: stripe.String("person@example.edu"),
}
params.SetStripeAccount("{{CONNECTED_STRIPE_ACCOUNT_ID}}")
cus, err := customer.New(params)

// Fetching an account just needs the ID as a parameter
acct, err := account.GetByID("{{CONNECTED_STRIPE_ACCOUNT_ID}}", nil);

    StripeConfiguration.ApiKey = "{{PLATFORM_SECRET_KEY}}";
var customerOptions = new CustomerCreateOptions {
    Email = "person@example.edu",
};
var requestOptions = new RequestOptions();
requestOptions.StripeConnectAccountId = "{{CONNECTED_ACCOUNT_ID}}";
var customerService = new CustomerService();
Customer customer = customerService.Create(customerOptions, requestOptions);

// Fetching an account just needs the ID as a parameter
var accountService = new AccountService();
Account account = accountService.Get("{{CONNECTED_STRIPE_ACCOUNT_ID}}");

    Authentication via API keys

    The second authentication option makes API calls using the connected account’s secret and publishable keys. How a platform receives a connected account’s secret key depends upon the connection method:

    • For Standard and Express accounts, it’s the access_token, provided by the OAuth flow
    • For Custom accounts, it’s in the keys[secret] property returned by the create account API call

    This code performs the same refund request as above using this second authentication method:

    curl https://api.stripe.com/v1/charges/{{CHARGE_ID}}/refunds \
  -u {{CONNECTED_ACCOUNT_SECRET_KEY}}: \
  -d amount=1000

    If you are using this method, we recommend that you perform authentication with every request, instead of setting the API key globally. All of Stripe’s libraries support this style of authentication on a per-request basis:

    # Not recommended: setting global API key state
Stripe.api_key = "{{CONNECTED_ACCOUNT_SECRET_KEY}}"
Stripe::Customer.create({
  email: "person@example.edu"
})

# Recommended: sending API key with every request
Stripe::Customer.create({
  {email: "person@example.edu"},
  {api_key: "{{CONNECTED_ACCOUNT_SECRET_KEY}}"} # account's access token from the Connect flow
})

    # Not recommended: setting global API key state
stripe.api_key = "{{CONNECTED_ACCOUNT_SECRET_KEY}}"
stripe.Customer.create(
  email="person@example.edu"
)

# Recommended: sending API key with every request
stripe.Customer.create(
  email="person@example.edu",
  api_key="{{CONNECTED_ACCOUNT_SECRET_KEY}}" # account's access token from the Connect flow
)

    // Not recommended: setting global API key state
\Stripe\Stripe::setApiKey("{{CONNECTED_ACCOUNT_SECRET_KEY}}");
\Stripe\Customer::create(
  ["email" => "person@example.edu"]
);

// Recommended: sending API key with every request
\Stripe\Customer::create(
  ["email" => "person@example.edu"],
  ["api_key" => "{{CONNECTED_ACCOUNT_SECRET_KEY}}"] // account's access token from the Connect flow
);

    // Not recommended: setting global API key state
Stripe.apiKey = "{{CONNECTED_ACCOUNT_SECRET_KEY}}";

Map<String, Object> params = new HashMap<String, Object>();
params.put("email", "person@example.edu");

Customer.create(params);

// Recommended: sending API key with every request
RequestOptions requestOptions = RequestOptions.builder().setApiKey("{{CONNECTED_ACCOUNT_SECRET_KEY}}").build();

Map<String, Object> params = new HashMap<String, Object>();
params.put("email", "person@example.edu");

Customer.create(params, requestOptions);

    // Not recommended: setting global API key state
const stripe = require('stripe')('{{CONNECTED_ACCOUNT_SECRET_KEY}}');
stripe.customers.create({
  email: 'person@example.edu'
});

// Recommended: sending API key with every request
stripe.customers.create(
  { email: 'person@example.edu' },
  { api_key: '{{CONNECTED_ACCOUNT_SECRET_KEY}}' } // account's access token from the Connect flow
);

    // Not recommended: setting global API key state
stripe := &client.API{}
stripe.Init("access_token", "{{CONNECTED_ACCOUNT_SECRET_KEY}}")
params := &stripe.CustomerParams{
  Email: stripe.String("person@example.edu"),
}
cus, err := customer.New(params)

// Recommended: sending API key with every request
params := &stripe.CustomerParams{
  Email: stripe.String("person@example.edu"),
  Key: "{{CONNECTED_ACCOUNT_SECRET_KEY}}",
}
cus, err := customer.New(params)

    // Not recommended: setting global API key state
StripeConfiguration.ApiKey = "{{CONNECTED_ACCOUNT_SECRET_KEY}}";
var customerOptions = new CustomerCreateOptions {
    Email = "person@example.edu",
};
var customerService = new CustomerService();
Customer customer = customerService.Create(customerOptions);

// Recommended: sending API key with every request
var customerOptions = new CustomerCreateOptions {
    Email = "person@example.edu",
};
var customerService = new CustomerService();
var requestOptions = new RequestOptions();
requestOptions.ApiKey = "{{CONNECTED_ACCOUNT_SECRET_KEY}}";
Customer customer = customerService.Create(customerOptions);

    Next steps

    See what API calls you can perform actions on behalf of your users:

    Was this page helpful? Yes No

    Send

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    Questions?

    We're always happy to help with code or other questions you might have. Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    On this page