Core Resources
Payment Methods
Products
Product Catalog
Commerce
Agentic Commerce
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury for Platforms
Payment Records
Account Evaluation
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

App Installs v1

An app install represents a Stripe App that is installed on an account. It reports the permissions, content security policy entries, and endpoints that the installing account has authorized, along with any that the app’s latest version requests but the account has not authorized yet. Use the Install API to install, reauthorize, and uninstall apps, and to check the state of existing installs.

Was this section helpful?YesNo
Create an app install
POST/v1/apps/installs
Update an app install
POST/v1/apps/installs/:id
Retrieve an app install
GET/v1/apps/installs/:id
List all app installs
GET/v1/apps/installs
Uninstall an app install
POST/v1/apps/installs/:id/uninstall

The App Install object v1

Attributes

  • idstring

    Unique identifier for the object.

  • accountstring

    The ID of the account that the app install belongs to.

  • appstring

    The ID of the app installed.

  • approval_requiredboolean

    Whether the installer must authorize pending permissions, content security policy entries, or endpoints. For private apps, approval_required stays false; creating or reauthorizing the install through the API installs the newest completed upload and grants its permissions.

  • channelenum

    The distribution channel associated with the app install.

    Possible enum values
    private_live

    A private app installed in live mode.

    private_test

    A private app installed in test mode.

    public

    The published version of the app.

    review

    The app as installed by Stripe for app review.

    testing

    A pre-release version of the app installed for external testing.

  • content_security_policy_grantedobject

    The content security policy entries authorized by the installer.

  • permissions_grantedarray of strings

    The permissions authorized by the installer.

  • permissions_pendingarray of strings

    The permissions requested by the latest app version that the installer has not authorized.

  • statusenum

    The status of the app install.

    Possible enum values
    install_failed

    The install did not complete. The app cannot be used.

    installed

    The app is installed and can be used. Access that the installer has not authorized yet is listed in the pending fields.

    installing

    The install is in progress.

    uninstall_failed

    The uninstall did not complete.

    uninstalling

    The uninstall is in progress.

More attributes

  • objectstring, value is "apps.install"

  • auth_codenullable string

  • content_security_policy_pendingobject

  • createdtimestamp

  • created_bynullable string

  • endpoints_grantedarray of strings

  • endpoints_pendingarray of strings

  • livemodeboolean

The App Install object
{
  "id": "appinst_test_61VGZmT4pXc8Rk2w41LUZiLcTVChK7Ab",
  "object": "apps.install",
  "account": "",
  "app": "app_61VGZkQ7mRbN3xPa41LUZiLcTVChQ9Ye",
  "approval_required": false,
  "auth_code": null,
  "channel": "public",
  "content_security_policy_granted": {
    "connect_src": [
      "https://api.example.com/"
    ],
    "image_src": [
      "https://cdn.example.com/"
    ]
  },
  "content_security_policy_pending": {
    "connect_src": [],
    "image_src": []
  },
  "created": 1725000000,
  "created_by": null,
  "endpoints_granted": [
    "https://example.com/stripe/webhook"
  ],
  "endpoints_pending": [],
  "livemode": false,
  "permissions_granted": [
    "customer_read",
    "event_read"
  ],
  "permissions_pending": [],
  "status": "installed"
}

Create an app install v1

POST /v1/apps/installs

Creates an app install. An account installs its own private app with its own key; public and testing installs are made from the Dashboard. An app developer acting on a connected account through Stripe-Account installs or reinstalls its app there, and an embedding platform can do the same once the app’s developer approves its request to embed the app. For a private app, creating an install installs the newest completed upload; when that version is already installed with nothing pending, the existing install is returned.

Parameters

  • appstringRequired

    The ID of the app to install.

  • channelenum

    The distribution channel to install from. Defaults to public, which only app developers and embedding platforms can use. An account installing its own private app must pass private_test or private_live, matching the mode of the API key.

    Possible enum values
    private_live

    A private app installed in live mode.

    private_test

    A private app installed in test mode.

    public

    The published version of the app.

    testing

    A pre-release version of the app installed for external testing.

  • code_challengestring

    For OAuth apps, the PKCE code challenge used to issue the auth_code returned on the install. Must be 43 to 128 characters and contain only letters, numbers, -, ., _, and ~. Only applies to installs made by the app developer or an embedding platform; ignored when an account installs its own private app.

  • code_challenge_methodstring

    The method used to derive code_challenge. Required when code_challenge is provided, and must be S256.

Returns

Returns the app install

curl https://api.stripe.com/v1/apps/installs \
  -u "sk_test_BQokikJOvBiI2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}" \
  -d app=app_61VGZkQ7mRbN3xPa41LUZiLcTVChQ9Ye \
  -d channel=public
Response
{
  "id": "appinst_test_61VGZmT4pXc8Rk2w41LUZiLcTVChK7Ab",
  "object": "apps.install",
  "account": "",
  "app": "app_61VGZkQ7mRbN3xPa41LUZiLcTVChQ9Ye",
  "approval_required": false,
  "auth_code": null,
  "channel": "public",
  "content_security_policy_granted": {
    "connect_src": [
      "https://api.example.com/"
    ],
    "image_src": [
      "https://cdn.example.com/"
    ]
  },
  "content_security_policy_pending": {
    "connect_src": [],
    "image_src": []
  },
  "created": 1725000000,
  "created_by": null,
  "endpoints_granted": [
    "https://example.com/stripe/webhook"
  ],
  "endpoints_pending": [],
  "livemode": false,
  "permissions_granted": [
    "customer_read",
    "event_read"
  ],
  "permissions_pending": [],
  "status": "installing"
}