## Stripe Apps: Building and Managing Integrations

This documentation set covers the development and management of Stripe Apps, a platform that allows developers to extend Stripe's functionality and embed custom user experiences directly within the Stripe Dashboard. It details how to build, authenticate, distribute, and manage these applications.

---

### Core Concepts and Getting Started

*   **Overview of Stripe Apps:** Understand the fundamental capabilities of Stripe Apps, including their ability to authenticate users, listen for events, and automate workflows, as well as design custom user interfaces within the Stripe Dashboard.
*   **Getting Started with Stripe Apps:** Learn the basics of app development by building, previewing, and updating a sample "Hello, world!" Stripe App. This includes setting up the Stripe CLI.
*   **How Stripe Apps Work:** Delve into the architecture of Stripe Apps, understanding their frontend (UI extensions) and backend components, and how to create apps for personal use or public distribution via the Stripe App Marketplace.

---

### Developing Your Stripe App

*   **App Manifest Reference:** Understand the `stripe-app.json` file, which describes how your app integrates with the Stripe platform, including fields for ID, version, name, icon, distribution type, API access type, redirect URIs, and permissions.
*   **API Authentication Methods:** Explore the three primary methods for authenticating requests to the Stripe API on behalf of your users: Platform key, OAuth 2.0, and Restricted API Keys (RAKs).
*   **OAuth 2.0:** Learn how to use the industry-standard OAuth 2.0 protocol to authenticate requests, including the user authentication flow and app manifest configuration.
*   **Restricted API Key Authentication:** Understand how to use Restricted API Keys (RAKs) for authentication, which provide a more secure way to grant specific permissions to your app.
*   **Authorization Flows:** Implement PKCE OAuth workflows to retrieve access tokens from OAuth providers directly within your Stripe App's UI extension.
*   **Server-Side Logic:** Add backend code to validate and process user actions and data, integrate with third-party systems, subscribe to webhook events, and implement long-lived app logic.
*   **Build a UI:** Learn to create custom user interfaces within the Stripe Dashboard using TypeScript, React, and Stripe's UI Extensions SDK and UI toolkit. This includes understanding UI extensions, viewports, and component hierarchy constraints.
*   **UI Components:** Familiarize yourself with the comprehensive library of prebuilt UI components available for building your app's interface, including components for layout, input, data display, and navigation.
    *   **Layout and Structure:** `Box`, `Inline`, `Divider`, `FocusView`, `ContextView`, `SettingsView`, `SignInView`, `OnboardingView`, `FullPageView`, `FullPageTabs`, `OverviewPage`.
    *   **Input and Controls:** `Button`, `ButtonGroup`, `Checkbox`, `DateField`, `Radio`, `Select`, `TextArea`, `TextField`, `Switch`.
    *   **Data Display:** `Badge`, `Banner`, `BarChart`, `Chip`, `DataTable`, `DetailPageModule`, `DetailPagePropertyList`, `DetailPageTable`, `Icon`, `Img`, `LineChart`, `Link`, `List`, `Menu`, `PropertyList`, `Sparkline`, `Spinner`, `Table`, `Tabs`, `TaskList`, `Toast`, `Tooltip`.
*   **Design Patterns:** Follow recommended design patterns for common app functionalities like onboarding, sign-in, settings, loading states, error handling, and navigation to ensure a consistent and intuitive user experience.
*   **Styling Your App:** Learn how to style UI components using provided design tokens to match the Stripe Dashboard's visual style and maintain consistency.
*   **App Settings Page:** Create a dedicated page within the Stripe Dashboard for users to configure their app's settings and authenticate with external services.
*   **Secret Store API:** Securely store and retrieve sensitive data, such as authentication credentials and tokens, using the Secret Store API.

---

### Testing and Debugging

*   **Enable Sandbox Support:** Configure your public app for sandbox installation, allowing users to evaluate app features and functionality in Stripe's testing environment.
*   **Enable Local Network Access:** Understand and grant Local Network Access (LNA) permissions for browser-based previewing of your app during development.
*   **UI Testing:** Learn to write unit tests for your app's user interface using Jest and provided testing utilities.
*   **Developer Tools:** Utilize bundled developer tools for type checking, linting, and testing your app's code.
*   **Test Your App Externally:** Set up and distribute test versions of your app to a limited group of testers before public release.

---

### Distribution and Management

*   **Distribution Options:** Explore the two primary methods for distributing your Stripe Apps: making them publicly available on the Stripe App Marketplace or sharing them privately with your team.
*   **Upload and Install Your App:** Learn the steps to upload your app to the test mode sandbox and install it on your Stripe account for team access.
*   **Publish Your App:** Follow the process for publishing your app to the Stripe App Marketplace, including app review requirements and best practices.
*   **App Review Requirements:** Understand the quality requirements for apps to be listed on the App Marketplace, focusing on transparency, usability, and adherence to Stripe's standards.
*   **Manage App Versions and Releases:** Learn about app versioning and releases to effectively manage changes and ship new versions of your app over time.
*   **Promote Your App:** Discover how to partner with Stripe to accelerate your app's growth through the Stripe Partner Ecosystem.
*   **Install Links:** Allow users to install public apps outside of the Stripe App Marketplace using integrated install link flows.
*   **Deep Links:** Create deep links that navigate users directly to your Stripe App within the Stripe Dashboard.
*   **Post-Install Actions:** Enable additional configurations or actions that occur after a user installs your app, either within the app itself or via an external link.
*   **Using Roles in UI Extensions:** Tailor app functionality to different user roles within the Stripe Dashboard by leveraging role information from the `userContext` object.

---

### Migration

*   **Migrate an Extension to Stripe Apps:** Understand why and how to migrate legacy extensions to the modern Stripe Apps platform for better discoverability and more granular permissions.
*   **Migrate a Plugin:** Learn about your options for migrating third-party integrations that previously required users to authenticate with secret API keys to Stripe Apps or Stripe Connect using secure authentication methods (OAuth 2.0, RAKs, or Stripe Connect).
    *   **Migrate a Plugin to an OAuth 2.0 App:** Specific guidance on migrating to OAuth 2.0 authentication.
    *   **Migrate a Plugin to a RAK App:** Specific guidance on migrating to Restricted API Key (RAK) authentication.

---

### Reference

*   **Stripe Apps CLI Reference:** Install and use the Stripe Apps command-line interface to manage your app's lifecycle, from creation to upload.
*   **Permissions Reference:** Understand the available events and their required permissions for your Stripe App to access user data and functionality.
*   **Extension SDK API Reference:** Access documentation for the Extension SDK API, including context props and utility functions for UI extensions.
*   **Viewports Reference:** Learn about the available viewports within the Stripe Dashboard where your UI extension can be rendered.
*   **Route Descriptors:** Navigate users within the Dashboard using route descriptors for soft, context-preserving navigation without full page reloads.