## Permissions Reference

A Stripe App requires specific permissions to access user data and interact with Stripe's API. These permissions are defined in your app's manifest file and must be accepted by account administrators during the installation process.

### Types of Permissions

Stripe Apps can request permissions for two main categories:

*   **Object Permissions:** These grant access to read or write specific Stripe API objects (e.g., `invoice_write`, `customer_read`).
*   **Event Permissions:** These allow your app to subscribe to and receive notifications about specific events occurring within a user's Stripe account (e.g., `charge.succeeded`, `customer.created`).

### Requesting Permissions

1.  **App Manifest (`stripe-app.json`):** List the required permissions within the `permissions` array in your app's manifest file. Each permission object should include:
    *   `permission`: The name of the permission (e.g., `invoice_write`).
    *   `purpose`: A clear explanation of why your app needs this permission. This explanation will be shown to users during installation.

    ```json
    {
      "id": "com.example.my-app",
      "version": "0.0.1",
      "name": "My Stripe App",
      // ... other manifest fields
      "permissions": [
        {
          "permission": "invoice_write",
          "purpose": "To create and update invoices on your behalf."
        },
        {
          "permission": "charge.succeeded",
          "purpose": "To notify you when a charge is successful."
        }
      ]
    }
    ```

2.  **Stripe CLI:** You can also manage permissions using the Stripe Apps CLI:

    ```bash
    stripe apps grant permission "PERMISSION_NAME" "EXPLANATION"
    ```

    Replace `PERMISSION_NAME` with the actual permission and `EXPLANATION` with a user-friendly description.

### Handling Insufficient Permissions

If your app attempts to perform an action for which it lacks the necessary permissions, Stripe will typically return an `invalid_request` error. Ensure your app gracefully handles such scenarios.

### Permission Names

Detailed lists of available permission names for objects and events can be found in the relevant sections of the Stripe documentation.