Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Overview
Versioning
Changelog
Upgrade your API version
Upgrade your SDK version
Developer tools
SDKs
API
    API v2
    API keys
    Stripe-Context header
    Daily changelog
    Rate limits
    Automated testing
    Metadata
    Expanding responses
    Pagination
    Domains and IP addresses
    Search
    Localization
    Error handling
    Error codes
Testing
Workbench
Event Destinations
Workflows
Stripe CLI
Stripe Shell
Developers Dashboard
Agent toolkit
Stripe health alertsBuild with LLMsStripe for Visual Studio CodeFile uploads
Security
Security
Extend Stripe
Stripe Apps
Stripe Connectors
Partners
Partner ecosystem
Partner certification
HomeDeveloper toolsAPI

Stripe-Context header

Perform API operations on related accounts.

Copy page

By default, API requests execute on the Stripe account that generated the accompanying API key. However, you can use the Stripe-Context header to perform an API request in the context of a related account.

Note

The Stripe-Context header supersedes the Stripe-Account header, which facilitates performing API operations on connected accounts. Stripe-Context expands the scope and the types of related accounts they can access.

API request scope

You can make API requests to operate within different scopes:

  • Your own account
  • Any connected account in your platform
  • Any v2 account with at least the merchant or recipient configuration

When you make an API request targeting an account other than that of the API key, you must identify the intended account by including the Stripe-Context header. The value depends on the relative relationship of the intended account to the API key used to make the request.

For example, consider an organization with multiple platform accounts representing different business lines. Each platform has connected accounts and one connected account has a recipient account.

Given this business structure, it’s possible to perform API requests using several different scopes. The following table shows the Stripe-Context format for each different scope that requires context based on its relationship to the account the requesting API key belongs to.

Requesting API key owner Scope accountStripe-Context format
Rocket RidesDriver SmithConnected account ID: acct_111a
Rocket DeliveriesCourier VegaConnected account ID: acct_333a
Rocket RidesFuel CityConnected account ID/Recipient ID: acct_111a/acct_111b

Example use cases

The following code sample shows a request where the Rocket US platform retrieves the available bank accounts for the recipient of its connected account. The recipient is the grandchild of the platform, so the context uses the format <connected account ID>/<recipient ID>.

Command Line
curl
curl https://api.stripe.com/v2/core/vault/us_bank_accounts \ -H "Authorization: Bearer {{PLAT_SECRET_KEY}}" \ -H "Stripe-Version: 2025-03-31.preview" \ -H "Stripe-Context: acct_111a/acct_111b"
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc