## Stripe Apps Documentation

This documentation suite 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.

---

### Core Concepts and Getting Started

*   **Stripe Apps Overview:** Provides a high-level introduction to Stripe Apps, their capabilities, and how they can be used to authenticate users, listen for events, automate workflows, and create custom UIs within the Stripe Dashboard.
*   **Getting Started with Stripe Apps:** Guides users through the initial steps of building a basic Stripe App, including setting up the development environment and creating a "Hello, world!" example.
*   **How Stripe Apps Work:** Explains the fundamental architecture of Stripe Apps, detailing the frontend and backend components and the different types of apps that can be built (backend, frontend, full-stack).
*   **Common Use Cases:** Outlines various scenarios and business needs that can be addressed by building Stripe Apps, categorized by app type (backend, frontend, full-stack).

---

### Building Your Stripe App

*   **Build an App:** General guidance on the app development process.
*   **Build a UI:** Details on creating custom user interfaces within the Stripe Dashboard using TypeScript, React, and Stripe's UI Extensions SDK and UI toolkit.
    *   **How UI Extensions Work:** Explains the system for rendering custom UIs within Stripe's products using sandboxed iframes and Stripe's UI components.
    *   **Next Generation UI Components:** Introduces early access to updated UI components for enhanced functionality and API design.
    *   **UI Components:** A comprehensive reference to the available UI components for building app interfaces, including Accordion, Badge, Banner, Button, Checkbox, Chip, DateField, Icon, Img, Inline, Link, List, Menu, Radio, Select, Spinner, Switch, Table, Tabs, TextArea, TextField, and Tooltip.
    *   **Component Hierarchy Constraints:** Defines rules for composing UI components to ensure predictable rendering.
    *   **Design Patterns:** Provides recommended patterns for consistent and scalable app design, covering areas like onboarding, action buttons, lists, and more.
    *   **Style Your App:** Guidelines on styling app components using provided design tokens to match the Dashboard's visual style.
    *   **Design Your App:** Introduces design tools, guidelines, and philosophy for building Stripe Apps.
*   **Add Server-Side Logic:** Explains how to integrate self-hosted backend services for secure third-party integrations, webhook event handling, and long-running app logic.
*   **API Authentication Methods:** Describes the different methods for authenticating requests to the Stripe API on behalf of users: Platform key, OAuth 2.0, and Restricted API Key (RAK).
    *   **OAuth 2.0:** Details the industry-standard OAuth 2.0 flow for generating access tokens.
    *   **Restricted API Key Authentication:** Explains how to use RAKs for secure, permissioned API access.
*   **Authorization Flows:** Guides on implementing authorization workflows, including PKCE OAuth.
*   **Store Secret Credentials and Tokens:** Information on using the Secret Store API to securely persist sensitive data like authentication credentials.
*   **App Settings Page:** How to create a customizable settings page for users to configure app preferences.
*   **Handle Different Modes:** Instructions on adapting apps to work seamlessly in both live and sandbox environments.
*   **Enable Sandbox Support:** How to enable your public app for installation in Stripe's testing environments.
*   **Enable Local Network Access:** Guidance on enabling local network access for app previewing.

---

### App Distribution and Management

*   **Distribution Options:** Explains the methods for sharing Stripe Apps, including public distribution via the Stripe App Marketplace and private sharing.
*   **Upload and Install Your Stripe App:** Steps for uploading your app for team members and installing it in test or live modes.
*   **Test Your App Externally:** How to set up and distribute test versions of your app to external testers before publication.
*   **Manage Your App's Versions and Releases:** Information on app versioning and managing releases for new updates.
*   **Publish Your App:** A guide on publishing apps to the Stripe App Marketplace, including the app review process.
*   **Stripe Apps Quality Requirements:** Details on the qualitative requirements for apps to be approved for the App Marketplace.
*   **Promote Your App:** Information on partnering with Stripe to grow app visibility and reach.
*   **Install Links:** How to allow users to install public apps outside of the Stripe App Marketplace.
*   **Deep Links:** Guidance on creating deep links to navigate users directly to specific sections of your Stripe App within the Dashboard.
*   **Post-Install Actions:** How to configure additional actions or configurations that occur after a user installs your app.

---

### Migration and Legacy Information

*   **Migrate an Extension to Stripe Apps:** Explains why and how to migrate legacy extensions to the newer Stripe Apps platform.
*   **Migrate a Plugin to Stripe Apps or Stripe Connect:** Provides options for migrating third-party integrations that previously relied on secret API keys.
    *   **Migrate a Plugin to an OAuth 2.0 App:** Specific guidance for migrating to OAuth 2.0 authentication.
    *   **Migrate a Plugin to a RAK App:** Specific guidance for migrating to Restricted API Key (RAK) authentication.
*   **Legacy Extensions:** Information and reference for the deprecated extensions integration pattern.

---

### Reference and Tools

*   **App Manifest Reference:** A detailed guide to the fields, types, and descriptions for your app manifest file (`stripe-app.json`).
*   **Stripe Apps CLI Reference:** Documentation on using the command-line interface to create, develop, configure, and upload Stripe Apps.
*   **Permissions Reference:** A list of available events and their required permissions for your app.
*   **Extension SDK API Reference:** Documentation for the Extension SDK API, including context props and utility functions for UI extensions.
*   **Viewports Reference:** A list of available viewports within the Stripe Dashboard where your app's UI extensions can be displayed.
*   **Route Descriptors:** How to implement soft, context-preserving navigation within the Stripe Dashboard using route descriptors.
*   **UI Extension Developer Tools:** Information on bundled developer tools for type-checking, linting, and testing your app's code.
*   **Sample Apps:** A collection of working Stripe Apps examples to use as a starting point for your own development.