## Stripe Apps Documentation

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 interfaces within the Stripe Dashboard.

### Core Concepts

*   **Stripe Apps Overview**: Provides a high-level introduction to Stripe Apps, explaining what they are, their capabilities, and how they can be used to authenticate users, listen for events, automate workflows, and create custom UIs within the Stripe Dashboard.
*   **How Stripe Apps Work**: Details the fundamental architecture of Stripe Apps, including the distinction between frontend and backend components, and how apps can be developed for personal use or published to the Stripe App Marketplace.

### Getting Started

*   **Getting Started with Stripe Apps**: Guides users through the initial steps of app development, including building, previewing, and updating a basic "Hello, world!" app. It also covers prerequisites like installing the Stripe CLI.
*   **Create an App**: A foundational guide on initiating the app development process.

### Building Your App

*   **Build an App**: General guidance on app creation.
*   **Build a UI**: Explains how to create custom user interfaces within the Stripe Dashboard using TypeScript, React, and Stripe's UI Extensions SDK and UI toolkit.
*   **Add Server-Side Logic**: Details how to integrate server-side logic with a self-hosted backend for secure third-party integrations, webhook event subscriptions, and long-running processes.
*   **Common Use Cases**: Outlines different app types (backend, frontend, full-stack) and provides examples of common business needs that can be addressed with Stripe Apps.
*   **Sample Apps**: Offers a collection of working examples and code snippets to help developers get started.

### App Authentication and Authorization

*   **API Authentication Methods**: Describes the various methods for authenticating requests to the Stripe API, including Platform Key, OAuth 2.0, and Restricted API Keys (RAKs).
*   **OAuth 2.0**: Provides specific guidance on implementing OAuth 2.0 for app authentication.
*   **Restricted API Key Authentication**: Explains how to use Restricted API Keys (RAKs) for secure and permissioned API access.
*   **Add Authorization Flows**: Details how to implement PKCE OAuth workflows within Stripe Apps.
*   **Store Secret Credentials and Tokens**: Covers the use of the Secret Store API for securely persisting sensitive data like authentication credentials.

### UI Components and Design

*   **UI Components**: A comprehensive reference for all available UI components within the Stripe Apps UI toolkit, including Accordion, Badge, Banner, Button, Input fields, and more.
*   **Next Generation UI Components**: Introduces upcoming UI components and features.
*   **Component Hierarchy Constraints**: Explains the rules and constraints governing how UI components can be composed.
*   **Design Your App**: Provides guidelines and philosophy for designing user interfaces for Stripe Apps.
*   **Style Your App**: Details how to style UI components using provided design tokens to maintain visual consistency with the Stripe Dashboard.
*   **Design Patterns**: Offers recommended patterns for common app functionalities like onboarding, sign-in, loading states, and more to ensure a consistent and user-friendly experience.

### App Management and Distribution

*   **Distribution Options**: Outlines the methods for sharing Stripe Apps, including public distribution via the Stripe App Marketplace and private distribution.
*   **Upload and Install Your Stripe App**: Guides users on how to upload and install their apps for team members or for testing.
*   **Manage Your App's Versions and Releases**: Explains how to manage app versions and releases, including publishing to the Stripe App Marketplace.
*   **How to Publish an App to the Stripe App Marketplace**: Provides a step-by-step guide for getting an app approved and listed on the marketplace.
*   **Stripe Apps Quality Requirements**: Details the quality standards and guidelines that apps must meet for marketplace review.
*   **Test Your App Externally**: Describes how to set up and distribute test versions of an app to external testers before public release.
*   **Enable Sandbox Support**: Explains how to enable sandbox installation for public apps, allowing users to evaluate features in a testing environment.
*   **Handle Different Modes**: Guides developers on adapting their apps to function correctly in both live mode and sandbox environments.

### Advanced Features and Integrations

*   **Embed Third-Party Stripe Apps**: Details how to use embedded components for Stripe Apps to allow customers to manage payment data within third-party applications.
*   **Marketing Software Integrations**: Specifically covers integrating marketing software, such as Mailchimp, using embedded components.
*   **Add Deep Links**: Explains how to create deep links to navigate users directly to specific sections of a Stripe App within the Dashboard.
*   **Using Install Links**: Describes how to generate install links to allow users to install public apps outside of the Stripe App Marketplace.
*   **Enable Post-Install Actions**: Covers how to support additional configurations or actions that users might need to complete after installing an app.
*   **Enable Local Network Access**: Explains how to enable local network access for app previewing, which is necessary for certain development workflows.
*   **App Analytics**: Details how to access and interpret app analytics to understand app performance and user engagement.
*   **App Settings Page**: Guides on creating a customizable settings page for users to configure their app preferences.
*   **Using Roles in UI Extensions**: Explains how to leverage user roles within UI extensions to tailor app functionality based on user permissions.

### Migration

*   **Migrate an Extension to Stripe Apps**: Provides reasons and instructions for migrating legacy extensions to the newer Stripe Apps platform.
*   **Migrate a Plugin to Stripe Apps or Stripe Connect**: Offers guidance on migrating third-party integrations that previously relied on secret API keys.
*   **Migrate a Plugin to an OAuth 2.0 App**: Specific instructions for migrating plugins to use OAuth 2.0 authentication.
*   **Migrate a Plugin to a RAK App**: Specific instructions for migrating plugins to use Restricted API Key (RAK) authentication.

### Reference

*   **App Manifest Reference**: A detailed guide to the `stripe-app.json` file, outlining all fields, types, and descriptions for app configuration.
*   **Stripe Apps CLI Reference**: Documentation for the command-line interface used to manage Stripe Apps.
*   **Permissions Reference**: Lists available events and their required permissions for Stripe Apps.
*   **Extension SDK API Reference**: Documents the context props and utility functions available to UI extensions.
*   **Viewports Reference**: Lists the available viewports within the Stripe Dashboard where UI extensions can be rendered.