Projects for platformsPrivate preview

Use the Stripe Projects API to add third-party services to your platform. Your users can create projects, connect providers, provision resources, retrieve credentials, and view usage without leaving your product.

This guide shows how platforms can integrate Stripe Projects into their products. To use Stripe Projects from the command line, see the Stripe Projects CLI.

Specifics of the API endpoints outlined below will be shared when access to the private preview is granted.

Before you begin

Before you register payment methods or provision paid resources for users, complete these setup steps.

1. Set up your Connect platform

   Platforms use connected accounts to represent your users in Stripe Projects.

   If you’re building a new SaaS platform, start with Build a SaaS platform, which uses Accounts v2 to create and manage connected accounts.

   If you already use Accounts v1, see Build a SaaS platform with Accounts v1.

2. Create connected accounts for users

   Create a connected account for each user who wants to use Stripe Projects services. This account owns the user’s projects, resources, and billing profile. Use the account creation flow from the Connect guide that matches your integration (either SaaS or Marketplace).

   Complete enough onboarding for Stripe Projects to read account owner profile data for the connected account. Setting contact_email alone might not provide the account owner profile data required to provision provider resources.

   Make sure the connected account includes the information required for user verification:

   • Verified email address
   • Date of birth
   • Phone number

   Store the returned Account ID with your internal user record. Use that Account ID in the Stripe-Context header for API calls you make for that user.

3. Protect credentials

   Your platform handles your Stripe secret key and user service credentials returned by providers.

   For your Stripe secret key:

   • Store it in an encrypted secrets manager.
   • Never expose it in client-side code, URLs, or browser-accessible storage.
   • Rotate it immediately if you suspect it’s been compromised.

   For user service credentials:

   • Store credentials in an encrypted vault or secrets manager.
   • Encrypt credentials at rest and in transit.
   • Never log credential values.
   • Give users a secure way to retrieve credentials.
   • Invalidate cached copies when you rotate credentials.

Authenticate requests

Use a restricted API key with the required Stripe Projects permissions when they’re available for your preview access. Otherwise, use the platform secret key confirmed during onboarding. Include the connected account ID for the user in the Stripe-Context header.

The API can change while it’s in preview, so confirm the current requests and responses during onboarding and before you update your integration.

Authorization: Bearer {{YOUR_PLATFORM_KEY}}
Stripe-Context: acct_user_abc123
Content-Type: application/json

Set up billing for paid services

Register the payment method profile that your platform already has on file for the user. Stripe Projects uses the registered payment method to facilitate billing when the user provisions paid provider services.

This setup is separate from provider and service consent. Collect provider and service consent when the user chooses what to provision.

Browse the catalog

List providers and services to build your service selection UI. Use the catalog responses as the reference for provider names, available services, pricing descriptions, required configuration, and provider terms.

Providers

The provider list returns one entry per provider. Each entry includes:

• A stable provider ID used in later API calls.
• Display name and description.
• Category (for example, database, hosting).
• Links to the provider’s privacy policy and terms of service.

Services

Fetch services filtered by provider. Each service entry includes:

• A stable service ID used when provisioning resources.
• Provider association (ID and name).
• Description and pricing details — either free or paid with a human-readable pricing description.
• A configuration schema (JSON Schema) describing any required inputs, such as region selection.

Your platform controls which catalog items users can select. You can filter providers and services by category, availability, pricing model, region, provider relationship, or your own product policy before showing them to users.

When a user chooses to connect a provider or add a service, show the relevant provider and service details from the catalog before you submit the provisioning request:

• Provider name, description, website, privacy policy, and terms of service links.
• Service name, description, category, pricing description, and required configuration.
• Any service-specific terms or acceptance text included in the service pricing or configuration details.

Collect the user’s explicit acceptance at that point, before you create an account request or provision a resource. Store the accepted provider, service, terms links, and timestamp with your internal record.

Create a project

Projects group related provider resources. Your platform decides how to map projects to its product model. You can let a user create one project or multiple projects, such as projects for different apps, workspaces, environments, or other units in your product.

You can also list all projects for a user. Each project entry includes the project ID, name, and creation timestamp.

Connect or link a provider account

Create an account request before you provision resources from a provider. Some providers connect immediately. Others require OAuth or more information from the user.

Provider integrations can support the existing provider state at multiple levels:

• Provider account: The provider can link to the user’s existing provider account instead of creating a new one.
• Team or organization: The provider can ask the user which team, organization, or workspace to use by returning needs_information from the account request.
• Resource: The provider can ask the user to select or link an existing resource during the resource provisioning flow.

Account request flow

Submit an account request for a provider. The response status will be one of:

If the status is needs_information, display the requested fields to the user, collect their input, and submit a response with the filled-in values. The API returns an updated status. Continue polling or re-submitting until the status reaches complete.

List provider connections

You can list all active provider connections for a user. Each connection entry includes a connection ID, provider ID, and active status.

Add a service

Provision a resource for the user. For paid services, Stripe Projects uses the user’s registered payment method for provider billing.

Provision a resource

Call the resource provisioning API with:

• The service identifier (from the catalog).
• The project ID to associate the resource with.
• The provider ID.
• Any configuration values required by the service’s configuration schema (for example, region, name).

The response returns a resource ID and an initial status of pending.

Poll for completion

Fetch the resource by its ID to track progress. The status field transitions through:

Poll until the status is complete before attempting to retrieve credentials.

Get credentials

After a resource reaches complete status, retrieve its access credentials.

Call the Environment Information API scoped to the project, with the reveal flag set to return credential values. The response returns one entry per resource, containing the credential key names and their values (for example, a DATABASE_URL connection string).

List resources

Show users the resources they’ve provisioned under a project.

Fetch the resource list scoped to a project ID. Each entry includes the resource ID, provider, service identifier, current status, display name, environment, and creation timestamp.

Manage resources

Update a service tier

Submit a resource update with a new service identifier and any required configuration. The resource transitions back to pending while the provider processes the change. Poll until the status returns to complete.

Rotate credentials

Submit a credential rotation request for a resource. Once the response status is complete, fetch fresh credentials from the Environment Information API and update your vault. Invalidate any cached copies of the old credentials immediately.

Remove a resource

Submit a removal request for a resource. The response returns a removed status when the provider has deprovisioned it.

View spend

Fetch charges for a project scoped to a time range. The response groups charges by provider, with each charge including the amount, currency, and authorization timestamp.

Update a payment method

When a user updates their card on your platform, register the new payment method using the same payment method registration call described in Set up billing. Active provider charges use the new payment method going forward.

Open a provider dashboard

Generate an authenticated deep link to a provider’s dashboard on behalf of a user. Submit a deep link request with the provider ID and a purpose (for example, dashboard). The response returns a short-lived URL and expiration time. Present this link to the user. Don’t store or cache it.

Handle errors

Errors follow the Stripe v2 error format: a top-level error object with a code and human-readable message.

Test your integration

Before you launch your integration, test these flows:

• Create a connected account for a test user.
• Verify the connected account is eligible for Stripe Projects and returns account owner identity details.
• Register a test payment method.
• Browse providers and services.
• Create a project.
• Connect a provider.
• Provision a free resource and retrieve credential keys with reveal=false.
• Provision a paid resource and verify billing.
• Reveal credential values only when your platform needs to store or display them.
• Rotate credentials and verify the new values.
• View spend for a project.
• Update the payment method and verify the billing profile.