Skip to main content
Version: 3.x

Apps

Architecture

Saleor Apps are separate applications that use GraphQL to talk to the Saleor server and receive webhooks with event notifications from Saleor. If the event payload lacks any data essential to the app, you can query additional data using GraphQL. In addition, the Saleor's API exposes all the actions from the dashboard, so your app can fully extend your shop behavior.

Type of Apps

  • local: create a custom App instance, and assign explicitly provided permissions. The app is fully manageable from the dashboard. You can change the assigned permissions and add webhooks or authentication tokens. With a local app, you can create an integration with some services which will parse the webhook payload.
note

If you're building a single service dedicated only to your shop, this solution will handle all your needs.

  • third-party: install the App in Saleor and proceed with all required steps to prepare the communication channel for the App.
    Installation is fully automated. Saleor uses a defined App manifest to gather all required information. If installed successfully, the App gets the possibility to attach to the Saleor Dashboard over the iframe, communicate with Saleor over the API, and use webhooks to subscribe for the given events.
note

If you're building an App that will be published in the marketplace, this solution is dedicated to you.

Dashboard integration

If your application needs additional configuration or presents data to the user, you can implement the configuration and the app view, which is displayed as an iframe in the dashboard.

The App manifest

The App manifest is a JSON file that describes the application, including its name, version, required permissions, and how it handles the store's data.

To read more, see App manifest section.

Permissions

The App access can be granularly assigned per-app basis. During installation, the user can choose which permissions to grant. Read permissions guide to learn more.

All requests from the dashboard view have the staff user JWT token so that additional permission checks can be done on the app side. The token contains permissions, being a common set of staff user and app permissions.

Authentication

Unlike regular users, Saleor Apps use a bearer token. The token is assigned at the App installation time and needs to be stored securely.

The authorization header for Apps has the following format:

Authorization: Bearer <app-token>

Verifying incoming payload - the secret key

To ensure that the incoming webhook payload is from a known host, Saleor adds the Saleor-Signature header to the request. Read more.