Hosted Apps

Let CARTO host and serve your application behind your organization's login

Private Preview: Hosted Apps is available to selected accounts during its Private Preview. To request access, contact your CARTO representative.

Introduction

As we've seen in previous concepts, most applications built with CARTO are static frontends: HTML, JavaScript and CSS files that call the CARTO APIs directly from the browser. Once built, they still need a place to be served from and, if they are private, a login for their users.

With Hosted Apps, CARTO hosts the application for you. You deploy the built files with the CARTO CLI, and CARTO serves them at a URL behind your organization's login:

• Users sign in with CARTO, including your Single Sign-On (SSO) when it is configured. There is no OAuth client to create and no login code to write.

• The application runs as the signed-in user. It receives that person's own access token, so it can only see and do what they can see and do in CARTO.

• Sharing works like it does for maps and workflows: keep the application private, or share it with your whole organization or with specific groups and users.

• Every deploy is a new version, and you can roll back to a previous one at any time.

Anything you can build with CARTO for Developers can be hosted this way, from a single map to a complete analytical application.

How it works

1. You build your application with deck.gl and @carto/api-client, as you would for any other CARTO application, and deploy the built files with carto app deploy. The files must follow a few bundle requirements, such as relative asset paths.

2. A user opens the application URL. CARTO checks that they are signed in and that the application is shared with them, and then serves the files.

3. The application reads the user's credentials from carto-info.json, a small file that CARTO serves next to the application for each user. It contains the user's access token and the API base URL, which the application uses with the CARTO APIs. See the carto-info.json contract.

4. Optionally, the application declares Named Sources in a carto.json manifest. CARTO registers them when you deploy, and the application runs its queries by name, so no SQL reaches the browser.

We recommend Hosted Apps when: your application is meant for people in your CARTO organization, and you would rather not set up hosting and a login for it.

Hosted Apps and authentication

A hosted application does not use any of the authentication methods directly. CARTO signs the user in and hands the application an ordinary OAuth Access Token that belongs to that user. Compared to a private application, the token is the same; what changes is that CARTO takes care of the login, so your code only has to read it. The runtime and authentication reference describes the session and how to renew it.

Choosing where to host your application

	Builder map	Hosted application	Your own hosting
Who can open it	CARTO users, or anyone if published	CARTO users you share it with	Anyone you allow, including the public
Login	Handled by CARTO	Handled by CARTO	Yours to implement, or an API Access Token if public
Interface	Builder's layout and components	Your own	Your own
Where it is served	CARTO	CARTO, under /app/<slug>/	Your infrastructure

Use a Builder map when its layout, styling and widgets already cover what you need. Use a hosted application when you need your own interface and the audience is inside your CARTO organization. Host it yourself when the application must be public, needs a backend of its own, or has to live on your own domain. For a public application, follow Build a public application; carto app package can prepare that public version from the same files.

Things to keep in mind

• Users need a CARTO login in your organization. Hosted applications cannot be public.

• Only static files are served. There is no server-side code. See Bundle requirements and limits.

• The application can only load resources and call APIs from CARTO and a short list of allowed origins, set by its Content Security Policy.

• Hosted applications cannot be embedded in other websites.

The complete list is in Limitations.

Learn more

• Hosting your first application deploys a one-file application in a few minutes.

• Hosting your application in CARTO walks you through building, deploying and sharing a complete application.

• The Hosted Apps reference describes the carto.json manifest, the runtime and authentication contract, and the bundle requirements and limits.