Runtime and authentication

How a hosted app is opened, the carto-info.json contract, sessions, sharing and versions

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

A hosted app has no server of its own. CARTO serves its files to signed-in users, and gives the app the credentials of the user who opened it.

Opening an app

Every file under /app/<slug>/ requires an app session. When someone opens the app URL without one, CARTO signs them in, with your organization's SSO when it is configured, and then opens the app at its start page. The path, query string and fragment of the original URL are not kept.

Only a page load can start a session, so users must open the app through its URL. Loading the app's files from another page does not work.

A signed-in user the app is not shared with gets 403. A slug that does not exist in their organization returns 404.

The app session

• It is a cookie, httpOnly and scoped to /app, so the app's JavaScript cannot read it and it is not sent to the rest of the workspace.

• It carries the user's access token, encrypted. The token is not exposed in URLs, browser history or logs.

• It lasts up to one hour, and never longer than the access token.

Requests for the app's files and for carto-info.json are authenticated by this cookie only. An Authorization header sent with them is ignored.

Renewing the session

When the session ends, carto-info.json returns 401, and other files of the app can no longer be loaded. The app can keep using the access token it already has until that token expires (expiresAt).

To renew the session, navigate the browser to /app/_session?slug=<slug>, as shown in Hosting your application in CARTO. CARTO signs the user in again, without any prompt while they are still logged in to CARTO, and reopens the app at its start page. Because it is a full page load, save any state the user would lose first. Renew when carto-info.json or a CARTO API returns 401.

The carto-info.json contract

The app fetches ./carto-info.json, relative to its own /app/<slug>/ path. CARTO generates it for each user and never caches it.

{
  "schemaVersion": 1,
  "accessToken": "eyJ...",
  "apiBaseUrl": "https://gcp-us-east1.api.carto.com",
  "expiresAt": 1789000000,
  "user": { "id": "auth0|...", "accountId": "ac_...", "email": "[e-mail]" }
}

Field	Type	Always present	Description
schemaVersion	integer	Yes	Version of this contract, currently 1. It changes only if the contract changes in a breaking way.
accessToken	string	Yes	The access token of the signed-in user, to send as Authorization: Bearer. No token is created for the app.
apiBaseUrl	string	Yes	The CARTO API base URL. Append the API path to it, for example /v3/sql/....
expiresAt	integer	No	When the access token expires, in Unix seconds. The app session can end earlier; see Renewing the session.
user	object or null	Yes	The signed-in user: id, accountId, and email, which is null when the token carries no email.

Other fields may be present. Ignore the ones you do not use.

Status	Meaning
200	The contract above.
401	No valid app session. Renew it as described above.
403	The user is signed in, but the app is not shared with them.
404	There is no app with this slug in the user's organization.

Two rules follow from this file being generated for each user:

• carto-info.json is a reserved filename. A bundle cannot include a file with that name at its root.

• Fetch it relative to the app path, as ./carto-info.json, and do not cache it. An absolute /carto-info.json does not resolve.

The app runs as the signed-in user

• Permissions are the user's. The app can see and do what that user can see and do in CARTO, through the same APIs, and nothing more.

• Usage is the user's. The app's API requests are the user's requests, and consume your organization's quota like any other request from that user.

• There are no app credentials. No token, client or service identity is created for a hosted app, so there is nothing to rotate.

• The bundle is visible to its users. Anyone who can open the app can read its files, so a bundle cannot hold a secret. Keep SQL in Named Sources, and never include a credential in the bundle.

Sharing

Sharing works as it does for maps and workflows.

carto app share flag	Who can open the app
--private	Only the owner.
--org	Everyone in the organization.
--group <ids>	The listed groups. Can be combined with --user.
--user <ids>	The listed users. Can be combined with --group.

• A newly deployed app is private.

• Each carto app share call replaces the previous sharing settings.

• Redeploying an app does not change its sharing.

• Only the owner can redeploy, share, roll back or delete the app. Sharing an app lets users open it, not change it.

Versions

Property	Behavior
Label	Set with carto app deploy --version <label>. Must match /^(?!.*\.\.)[a-zA-Z0-9.:_-]{1,64}$/: 1 to 64 letters, digits, ., :, _ and -, with no ...
Default label	The UTC date and time of the deploy.
Immutability	A deployed version cannot be changed. Deploying an existing label again fails.
Active version	Exactly one version is served at a time. Each deploy activates the version it creates.
Rollback	carto app rollback <slug> <version> makes a previously deployed version the active one.

A rollback only changes the files that are served. The URL, the sharing settings and the app's Named Sources stay as they were. If an older bundle needs different Named Sources, deploy it again instead of rolling back to it.

Users who already have the app open keep the files their browser loaded until they reload the page.

Related

• App manifest (carto.json): the Named Sources the app declares.

• Bundle requirements and limits: client-side routing, response headers and the CSP.

• Authentication methods: how this compares with API Access Tokens and OAuth.