# Projects for platforms

Use the Stripe Projects API to create projects, provision services, manage credentials, and view usage for your connected accounts.

> The Stripe Projects API is in private preview and subject to change. Contact your Stripe representative or email [projectsforplatforms@stripe.com](mailto:projectsforplatforms@stripe.com) for access and onboarding.

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](https://docs.stripe.com/projects.md).

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* (A person or business accepting payments or receiving payouts on a Connect platform) to represent your users in Stripe Projects.

   If you’re building a new SaaS platform, start with [Build a SaaS platform](https://docs.stripe.com/connect/saas.md), which uses Accounts v2 to create and manage connected accounts.

   If you already use Accounts v1, see [Build a SaaS platform with Accounts v1](https://docs.stripe.com/connect/end-to-end-saas-platform.md).

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](https://docs.stripe.com/connect/saas/tasks/create.md) or [Marketplace](https://docs.stripe.com/connect/marketplace/tasks/create.md)).

   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](https://docs.stripe.com/context.md) 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](https://docs.stripe.com/keys/restricted-api-keys.md) 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.

```http
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:

| Status | Meaning |
| --- | --- |
| `complete` | The provider connection was established immediately. |
| `needs_information` | The provider needs additional input from the user — for example, which team or organization to connect. |

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](https://docs.stripe.com/projects/platform-integration.md#set-up-billing-for-paid-services) 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:

| Status | Meaning |
| --- | --- |
| `pending` | The provider is provisioning the resource. |
| `complete` | The resource is ready. |
| `error` | Provisioning failed. Check the error details. |
| `needs_information` | Additional input is required (same pattern as account requests). |

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).

> #### Credential security
> 
> Credentials are sensitive. Store them in your platform’s encrypted vault or secrets manager. Never log credential values. Give users a secure retrieval mechanism, such as injecting credentials into a runtime environment, displaying them once at provisioning time, or writing them to an encrypted local store.

## 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](https://docs.stripe.com/projects/platform-integration.md#set-up-billing-for-paid-services). 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`.

| Code | When it happens | How to fix it |
| --- | --- | --- |
| `payment_method_not_accessible` | The payment method is invalid or not shareable. | Verify that the payment method and customer belong to your platform. |
| `payment_method_required` | The user tries to provision a paid service before registering a payment method. | Register a payment method for the user first. |
| `provider_failure` | The provider returned an error. | Check the error message and retry, or contact the provider. |
| `provider_reauth_required` | The provider connection expired. | Create a new account request for the provider. |
| `invalid_resource_configuration` | The service configuration is invalid. | Check the service’s configuration schema from the service listing. |
| `not_found` | The project or resource doesn’t exist. | Verify the ID and retry. |

## 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.

## See also

- [Stripe Projects CLI](https://docs.stripe.com/projects.md)
- [Provider intake for Stripe Projects](https://docs.stripe.com/projects/provider-intake.md)