App architecture and authorization options

To accommodate diverse application requirements, the Marketplace lets you choose between two architectural styles: client-side and full-stack. In addition, you can choose between two authorization options: the built-in authorization managed by the Marketplace SDK, and custom authorization with Auth0 provided by Sitecore.

Both architectures support both authorization options, so you can combine them depending on your application requirements.

This topic describes all the available options and the differences between them. To help you decide, see also Choosing the right architecture and authorization. We recommend that you make these choices during the planning phase because they affect how you create and build your app in a later step.

Tip

For your first Marketplace app, we recommend that you create a client-side app with built-in authorization. This is the simplest option, ideal for getting started with the Marketplace. You can opt in to more complex options later, as your requirements change.

Architecture

You can choose from the following options for your app's architecture:

  • Client-side - Marketplace apps that run entirely in the user's web browser. All API requests from the app to SitecoreAI APIs run indirectly via the web browser.

    The client-side architecture is ideal for simple UI extensions and functionalities that use browser-based logic without server-side processing. It is not ideal for apps that require direct interactions with SitecoreAI APIs.

  • Full-stack - Marketplace apps that have both client-side and server-side components. You can make client-side API requests to SitecoreAI APIs indirectly, via the web browser, or server-side API requests directly from the app.

    Important

    To make server-side API requests to SitecoreAI APIs, you must use custom authorization.

    The full-stack architecture is ideal for apps that require direct interactions with SitecoreAI APIs and for implementing features that are best managed on the server. This includes AI-powered apps, such as AI agents and agentic workflows. For example, Marketplace apps that use the Sitecore Marketer MCP.

Authorization

You can choose from the following options for your app's authorization:

  • Built-in authorization - the Marketplace SDK automatically manages authorization, abstracting it away from the developer.

  • Custom authorization - optionally, you can replace the built-in authorization with Auth0 authorization instead. You must use custom authorization if your app needs to make server-side API calls to SitecoreAI APIs. In this scenario, you must:

    • Set up a custom DNS for local development before you create a Marketplace app.

    • If building a custom Marketplace app - select API access during app configuration, create client credentials so your Marketplace app can access a Sitecore user token, and then install the Marketplace app in at least one environment. You then use the Marketplace SDK to retrieve Context IDs. At the end of this process, the Marketplace app is authorized to access SitecoreAI APIs.

      If building a public Marketplace app - select API access during app configuration, create client credentials so your Marketplace app can access a Sitecore user token, and then install the Marketplace app in at least one environment. You then use the Marketplace SDK to retrieve Context IDs. At the end of this process, the Marketplace app is authorized to access SitecoreAI APIs.

    In the custom authorization flow, you can make server-side SitecoreAI API requests by using the experimental tooling in the Marketplace SDK. The experimental tooling automatically retrieves the Sitecore user token and refreshes it as needed using Auth0. Then, the SDK attaches the token and the required headers to every SitecoreAI API request.

    Note

    If you make your app available in multiple organizations, make sure your app handles session invalidation and prompts the Marketplace app user to log in for each organization. Consider a scenario where a user opens your app in one organization, then switches to another organization and opens your app again. If you don't handle session invalidation, the user will have to authenticate themselves for the first organization, but not for the second organization. As a result, the user will get 401 Unauthorized errors for their API requests in the second organization. By implementing session invalidation and a new login for each organization, you ensure that the user logs in to your app in each organization and will not get 401 Unauthorized errors for their API requests.

Do you have some feedback for us?

If you have suggestions for improving this article,