## Stripe Apps: Building and Managing Integrations

This documentation set provides comprehensive guidance on developing, deploying, and managing applications that extend Stripe's platform. It covers the entire lifecycle of a Stripe App, from initial setup and authentication to UI development, distribution, and ongoing maintenance.

### Core Concepts

*   **Stripe Apps Overview:** Understand the fundamental concepts behind Stripe Apps, including their purpose, capabilities, and the overall architecture.
*   **How Stripe Apps Work:** Delve into the mechanics of Stripe Apps, learning about their components, and how they integrate with the Stripe Dashboard.
*   **App Manifest Reference:** Learn how to define your app's integration with Stripe using the `stripe-app.json` file, including essential fields and configurations.
*   **API Authentication Methods:** Explore the different ways your app can authenticate requests to the Stripe API, including Platform Key, OAuth 2.0, and Restricted API Keys.
*   **Server-Side Logic:** Discover how to add backend code to your Stripe App to validate and process user actions and data, enabling complex integrations.
*   **UI Extensions:** Understand how to build custom user interfaces within the Stripe Dashboard using TypeScript, React, and Stripe's UI Extensions SDK.
*   **Common Use Cases:** Explore practical examples of Stripe Apps, categorized by their architecture (backend, frontend, full-stack), to inspire your development.

### Development and Design

*   **Getting Started with Stripe Apps:** Follow a step-by-step guide to build your first Stripe App, including setting up the Stripe CLI.
*   **Build a UI:** Learn the process of creating, testing, and editing custom UIs for your Stripe App using Stripe's UI toolkit.
*   **UI Components:** Familiarize yourself with the comprehensive library of pre-built UI components available for building consistent and user-friendly interfaces. This includes detailed documentation for components like:
    *   **Layout and Structure:** `Box`, `Inline`, `Stack`, `Tabs`, `FullPageTabs`, `FullPageView`, `OverviewPage`
    *   **Input and Interaction:** `Button`, `ButtonGroup`, `Checkbox`, `DateField`, `Radio`, `Select`, `Switch`, `TextField`, `TextArea`, `SearchField`
    *   **Information Display:** `Accordion`, `Badge`, `Banner`, `BarChart`, `Chip`, `ContextView`, `Divider`, `Icon`, `Img`, `LineChart`, `Link`, `List`, `Menu`, `PropertyList`, `Sparkline`, `Spinner`, `Table`, `TaskList`, `Toast`, `Tooltip`
    *   **Workflow and Navigation:** `FocusView`, `FormFieldGroup`, `OnboardingView`, `SignInView`, `SettingsView`
*   **Design Patterns:** Follow Stripe's recommended design patterns to ensure a consistent, clear, and scalable user experience for your app. This includes guidance on:
    *   Onboarding flows
    *   Sign-in and settings sign-in
    *   Demo content presentation
    *   Action buttons and back links
    *   Communicating state and handling loading/waiting screens
    *   Managing empty states and filter controls
    *   Full-page app layouts and list displays
*   **Styling Your App:** Learn how to style your app using Stripe's provided design tokens to match the Dashboard's visual appearance.
*   **Component Hierarchy Constraints:** Understand the rules governing how UI components can be composed to ensure predictable and functional UIs.
*   **UI Testing:** Discover utilities and helpers for writing unit tests for your app's user interface.

### Authentication and Authorization

*   **API Authentication Methods:** Choose the appropriate authentication method for your app, including Platform Key, OAuth 2.0, and Restricted API Keys.
*   **OAuth 2.0:** Implement industry-standard OAuth 2.0 for secure user authentication and authorization.
*   **Restricted API Key Authentication:** Utilize Restricted API Keys (RAKs) for more granular control over API access.
*   **Authorization Flows:** Implement PKCE OAuth workflows to retrieve access tokens from OAuth providers directly within your Stripe App.
*   **Store Secret Credentials and Tokens:** Securely persist sensitive data like authentication credentials using the Secret Store API.

### Deployment and Distribution

*   **Distribution Options:** Learn how to make your Stripe Apps available to users, either privately or through the Stripe App Marketplace.
*   **Upload and Install Your Stripe App:** Follow the steps to upload your app for testing and make it available to your team.
*   **Publish Your App to the Stripe App Marketplace:** Understand the process of getting your app reviewed and listed on the global Stripe App Marketplace.
*   **Stripe Apps Quality Requirements:** Familiarize yourself with the qualitative requirements for apps to be accepted on the App Marketplace.
*   **Test Your App Externally:** Set up and distribute test versions of your app to gather feedback before official release.
*   **Manage Your App's Versions and Releases:** Learn about app versioning and releases to effectively manage changes over time.

### Migration and Legacy

*   **Migrate an Extension to Stripe Apps:** Understand why and how to migrate existing legacy extensions to the modern Stripe Apps platform.
*   **Migrate a Plugin to Stripe Apps or Stripe Connect:** Explore your options for migrating third-party integrations that previously relied on secret API keys.
*   **Legacy Extensions:** Find information about the deprecated extensions integration pattern for historical reference.

### Advanced Features and Configuration

*   **Enable Local Network Access:** Configure local network access for app previewing and development.
*   **Enable Sandbox Support:** Ensure your public app can be installed and tested in Stripe's sandbox environments.
*   **Handle Different Modes:** Adapt your app to function correctly in both live mode and sandbox environments.
*   **Add Deep Links:** Create deep links to navigate users directly to specific pages within your Stripe App in the Dashboard.
*   **Install Links:** Allow users to install public apps outside of the Stripe App Marketplace.
*   **Post-Install Actions:** Support additional configurations that occur after a user installs your app.
*   **App Analytics:** Access analytics to understand how your app is being used and its performance.
*   **Embedded Stripe Apps:** Integrate third-party Stripe Apps using embedded components, allowing users to manage payments data within other applications.
*   **Viewports Reference:** Understand the different viewports available for rendering your app's UI within the Stripe Dashboard.
*   **Route Descriptors:** Implement soft, context-preserving navigation to Dashboard pages from your Stripe App.
*   **Using Roles in UI Extensions:** Tailor app functionality based on user roles within the Stripe Dashboard.
*   **Developer Tools:** Utilize bundled developer tools for type-checking, linting, and testing your app's code.
*   **Upgrade Stripe's UI Extension SDK:** Learn how to upgrade your app to the latest version of the UI extension SDK and manage breaking changes.
*   **Back-end App Example:** Build a Stripe app that performs backend processing without a user interface.
*   **Front-end App Example:** Build a Stripe app that renders a user interface in the Stripe Dashboard.
*   **Full-stack App Example:** Build a Stripe app with both a user interface and backend functionality.