Skip to main content

Installing and Managing Apps

Apps connect BoxNCase to payment, tax, fulfillment, analytics, content, and custom business systems. Install them through the Dashboard or GraphQL API; server command-line access is not part of the managed platform.

Before installation​

  • Confirm the app provider and its support owner.
  • Review every requested permission.
  • Use a test workspace before production.
  • Verify that the manifest and registration endpoints use public HTTPS URLs.
  • Decide who can rotate credentials or remove the integration.

Permissions​

An app can access only the operations allowed by its approved permissions. Review permissions during installation and reject any scope that is broader than the app's documented workflow. The installing staff member must hold every permission they grant to the app.

Install from the Dashboard​

  1. Open Extensions → Explore to choose an approved extension, or select Install external app for an app your organization operates.
  2. For an external app, enter its public manifest URL.
  3. Review the app name, provider, endpoints, and requested permissions.
  4. Approve the installation.
  5. Open the installed app and complete its configuration.
  6. Run a test workflow before enabling it in production operations.

If the app provides a tokenTargetUrl, BoxNCase completes a server-to-server token exchange with that endpoint. The app must store the token securely and return a successful response to finish installation.

Installation using GraphQL API​

Use appInstall when an authorized internal tool manages installation. The manifest must be publicly reachable and the caller must hold the required app permissions.

mutation InstallApp($input: AppInstallInput!) {
  appInstall(input: $input) {
    appInstallation {
      id
      status
      appName
      manifestUrl
    }
    appErrors {
      field
      message
      code
      permissions
    }
  }
}
{
  "input": {
    "appName": "Order Operations",
    "manifestUrl": "https://integrations.example.com/boxncase/manifest",
    "permissions": ["MANAGE_ORDERS"],
    "activateAfterInstallation": true
  }
}

Track the returned installation with appsInstallations. A pending or failed installation does not grant the app access.

Retry or remove an installation​

Use appRetryInstall after fixing a temporary manifest, endpoint, or permission problem. Remove failed attempts with appDeleteFailedInstallation. For an installed app, deactivate it before removal when you need a controlled shutdown.

Before removing an app, confirm whether it owns webhook subscriptions, payment configuration, scheduled jobs, or data that must be exported.

Security​

App tokens are secrets. Do not display them in the browser, include them in client bundles, or send them through support tickets. Use one installation per workspace and environment, and rotate credentials after suspected exposure.

See App permissions and Webhooks.