Organisation API keys
Use the same API keys across your Stripe Organisation.
If you have multiple Stripe business accounts in an organisation, you can configure a single API key at the organisation level. Organisation-level API keys provide the following functionality:
-
Access any account : Use organisation API keys to access resources of any account within the organisation.
-
Restrict permissions : Restrict organisation API keys to grant read or write permission to only specific resources.
-
Centralised management : Create and manage organisation API keys on the API keys tab of your organisation’s Dashboard.
Behaviour
Organisation API keys are prefixed sk_org. Like account-level restricted API keys (RAKs) or secret keys, you can limit their permissions, and they support sandboxes and live mode.
Organisation API keys are different from account-level API keys in several ways:
- All organisation API keys are secrets. Unlike accounts, organisations don’t have publishable API keys.
- Organisation API keys all have the same sk _ org prefix, regardless of their permission levels. (There’s no rk _ org prefix.)
- All API requests made with an organisation API key that target a specific account must include the Stripe-Context header to identify the affected account.
- All API requests made with an organisation API key must include the Stripe-Version header to ensure consistency and predictability across your organisation’s integrations.
Security considerations
Because organisation API keys are secrets, you must follow best practice to store and use them safely. Use the same precautions you’d use for a restricted or secret API key.
Use an organisation API key only when you need to perform operations across multiple accounts or on the organisation itself. Don’t use an organisation API key if you need to access only one account.
Use organisation API keys
Your code or the Stripe SDK sends your organisation API key as a bearer token in an Authorization header, the same way you’d use a restricted or secret API key.
When you use an organisation API key, you must also:
- Specify an API version by including a Stripe-Version header. When you use a Stripe SDK , the SDK automatically sets the API version.
- Include the Stripe-Context header to identify the affected account when your request targets a specific account.
For example, given the following organisation structure:
Organization (org_6SD3oI0eSQemPzdmaGLJ5j6)
├── Platform account (acct_1R3fqDP6919yCiFv)
| └── Connected account (acct_1032D82eZvKYlo2C)
└── Standalone account (acct_1aTnTtAAB0hHJ26p)
You can use the organisation API key to access the balance of the standalone account. You can also use the same key to make the same call for the platform connected account.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
In the preceding code example, replace {{the related setting}} with an organisation API key and replace {{the related setting}} with the relevant value from the organisation structure above:
- For the standalone account, use acct _ 1aTnTtAAB0hHJ26p .
- For the connected account, use a path that identifies both the platform and the connected account, following the format acct _ 1R3fqDP6919yCiFv/acct _ 1032D82eZvKYlo2C .
You must specify the relevant account using the context and the API version in any API request using an organisation key.
Organisations don’t have publishable API keys because they can’t accept payments. You can use your organisation API key to create a PaymentIntent for any account in your organisation, but you must use existing account-specific publishable keys for client-side operations.