Manage Data Apps

An Astrato Data App keeps the same identity and URL when you publish updated content. You manage it as a publication through the CLI, lobby or MCP. Use labels to organize dashboards for purposes such as development, testing, and production.

Stability: preview. The capability is available only in enabled Astrato environments. Check the tools exposed by your Nash MCP connection before using it; Data App tools are hidden while the feature is disabled.

Creating a dashboard reserves an unpublished publication with an identity and access grants. It does not upload content or make an app available. Use astrato publish for a local project, or the Private Preview App Builder Publish action for a saved browser project. Astrato verifies the uploaded static files before replacing the content currently served by the publication. If an upload fails, the current content remains available.

A service limit prevents an app from loading

If a publication returns publication_header_limit_exceeded, it could not load because a service limit was exceeded. Contact Astrato support and share the response’s requestId. This error has retryable: false: repeatedly retrying the same request will not resolve the limit. Other publication failures keep their own error codes and retry guidance.

Manage publications in the lobby

Data Apps are listed in the Library, the first tab of Analytics, with workbooks and pinned questions, as described in Home and navigation. The list contains the publications you can access, including unpublished ones. Filter it by type to see Data Apps alone, and use the status tabs to see published, unpublished or draft apps.

An app’s properties show where it was made, under Made in: Astrato for Builder apps, External for known apps created outside Builder, and Unknown for older apps without reliable provenance. Choose Edit Data App from the three-dot menu at the end of the row to continue editing a Builder app’s saved source when Builder is enabled and you can manage the app. View opens a published app’s hosted link, the viewer-facing app.

Choose Properties in a row’s action menu, or for a published app select its Published Version tag, to open the right-side property panel. Selecting the row itself opens a published app, an App Builder draft in the App Builder, and the panel for any other app without an address. Change its name or labels, open a published app, unpublish it, or delete it. Each action is available only with the corresponding permission. Refresh after another person’s edit causes a version conflict.

Use the panel’s Manage Access tab or the row’s Manage access action to open the same access editor used elsewhere in the lobby. Choose users, groups or everyone in your tenant. View grants read access; Edit grants read and metadata-update access. Full access additionally includes Publish, Delete and Manage access. Custom access lets you select these independently. Publishing permission does not imply deletion permission, and editing metadata does not grant publishing permission.

Unpublishing keeps the publication for later publishing. Deleting removes it from the catalog, disables its URL and prevents further publishing to that ID. Audit records and stored files remain; this action does not erase objects from tenant storage. Both actions require confirmation.

Create an unpublished target through the CLI or the MCP tools below. Build and publish a local project through the CLI publication workflow. Builder projects use the explicit Publish action after their private source has saved. The lobby does not run build scripts or upload source code. When Data Apps are disabled, their Create entries, catalog results and lineage details are hidden. Creation and publication requests are also unavailable through the CLI, MCP and Nash. App Builder requires its own availability setting as well. Disabling Data Apps also disables publication management and viewer API requests; it is not a creation-only restriction.

Tenant ownership and sign-in

Newly published files use your tenant’s existing storage. You do not provide a separate bucket or cloud credentials when publishing. Republishing an older publication keeps its identity and access grants.

Opening a dashboard uses your existing Astrato session. Some Astrato environments also show an OAuth consent screen; approve it to continue. If you are signed out, complete the normal Astrato login and return to the dashboard. Publication permissions still determine whether you can open it; signing in does not grant access to another tenant’s content.

Viewer sign-in requests publication:read for dashboard access, schema:read for its semantic model and data:access-token for a short-lived data grant. These viewer scopes do not grant publishing or access-management permissions. The data grant’s capabilities remain governed by your Astrato permissions. MCP authoring uses the separate scopes listed below.

Public access and embedding

Public access, expiry controls and embedding are available only when your administrator enables publication access settings. Until then, authenticated standalone publications and their user and group access editor remain available, the CLI rejects access-setting changes, and MCP and Nash do not offer these settings.

In the property panel’s Public access tab, set Data App audience to Public. Anyone with the link can access. to admit anonymous viewers. Eligible public publications open without a sign-in redirect. Active public sessions renew automatically; expired, unavailable or forbidden publications show an error instead of starting login. Publications set to None. Users must sign in continue to require your Astrato session. Your tenant must enable the External embed links system setting. Public data also needs Visible to everyone on both the semantic layer and its data connection. A public viewer uses an anonymous identity even when already signed in to Astrato; the app never borrows the author’s data permissions.

A Data App can be public only when its data connection uses one shared credential: a password, key pair or service account. If the connection signs each viewer in with their own identity (OAuth), or is a dynamic connection that uses each viewer’s own settings, a public viewer has no identity to connect with. The Public access tab then shows Public unavailable and gives the reason. The editor, the CLI and MCP all refuse to make such an app public. Astrato also refuses while it cannot read how the connection authenticates, and while the semantic layer is unpublished. An app that is already public keeps its audience.

While the audience is public, Data for public viewers shows whether the semantic layer and its data connection are open to anybody. When you apply a change to Public. Anyone with the link can access., a confirmation lists each one that is not open yet, ticked. Confirming grants anybody read access on the ticked ones first, then makes the app public. If a grant is refused, for example because you cannot manage that resource’s access, the app stays as it was and the message names the resource. For an app that is already public, use Grant public data access… to open what is still missing. The grant gives workspace members nothing, but access settings list it as Visible to everyone. Other semantic layers on the same connection stay closed to public viewers unless they allow anybody too. Where the tab shows Public unavailable, it offers no grant, since the connection could not serve a public viewer anyway.

Use Expires on to choose an optional expiry date from the calendar, or leave it empty. New date selections expire at the end of that day in UTC. Editing other settings preserves any existing precise expiry timestamp. Enable Allow embedding and enter the permitted hostnames, one per line, to embed the publication. For example, portal.example.com allows that HTTPS host and *.example.com allows its subdomains. Every ancestor of a nested iframe must be allowed. Embedding is disabled by default.

Public embeds open without a sign-in prompt. Authenticated embeds show a sign-in button that opens a separate window. Embedded sessions require browser support for partitioned cookies; if browser policy blocks them, open the publication directly.

These settings require Manage access permission. Access changes can take up to five minutes to affect files already authorized for a viewer. Already-issued data tokens retain their remaining lifetime.

The MCP astrato_dashboard_freeform_update tool accepts audience, expireAt and embedding: { enabled, allowedDomains } with expectedVersion. Add grantPublicDataAccess: true with audience: "public", or on its own for an app that is already public, to grant anybody read access on the app’s semantic layer and data connection first. The response lists each under publicDataAccess as granted or already-open; one already open is left as it is. Sent on its own, it changes neither the app nor its version, so send it alone to re-check an app that is already public: sending audience: "public" again with it saves the app and moves its version. Each grant needs permission to manage that resource’s access, and OAuth clients also need publication:manage-access. If a grant is refused, the app is not changed and the error names any resource the call had already opened, which stays open. On a data connection that cannot serve public viewers, as described above, both audience: "public" and grantPublicDataAccess fail with public_data_connection_per_viewer and nothing is granted. The CLI exposes the audience, expiry and embedding settings:

astrato publications update <publication-id> --expected-version <version> \
  --audience public --embedding true --embed-domain portal.example.com

Use --expire-at <UTC-timestamp> to set an expiry, or --expire-at none to remove it.

SQL behind visualizations

Apps do not currently receive the SQL the engine ran for each visualization, in App Builder preview, astrato dev or published Apps, so the starter’s Show SQL button does not appear. There is no System settings control for it. The query response still carries the SQL, so a viewer with browser developer tools can see it; do not rely on Apps to keep query logic confidential.

Reserved paths and reporting

Keep /.well-known/security.txt, /_astrato and every path below /_astrato/ out of your build output. Astrato rejects these platform-owned paths during upload preparation, including case variants. Other /.well-known/ files remain available for your application. Artifact paths must be literal relative paths without %, ?, #, backslashes, empty segments or dot segments; provide Unicode filenames directly rather than URL-encoding them.

On hosting environments with publication reporting configured, open /.well-known/security.txt on your dashboard’s host for Astrato’s vulnerability-disclosure contact. Use /_astrato/report-abuse on that host to open the configured abuse-reporting form. These platform-owned endpoints require no dashboard sign-in and cannot be replaced by uploaded files. They are available whether or not the dashboard content is published.

Vulnerability disclosure and reports of abusive content use separate channels. A report does not automatically unpublish a dashboard.

MCP tools

MCP and Nash manage publications. They do not build app code, upload files or publish content. Contract 6.0.0 removes the prepare/complete publishing tools; reconnect and refresh tool discovery if a client cached the earlier schema. Use the CLI publication workflow for a local project, or the Builder Publish action for a saved Builder project.

Tool	Scope	Purpose
astrato_dashboard_freeform_create	publication:write	Reserve an unpublished publication for a semantic layer
astrato_dashboard_freeform_update	publication:write	Change name, labels or hosting; when publication access settings are enabled, also audience, expireAt and embedding
astrato_dashboard_freeform_list	publication:read	List Data Apps the current user can view
astrato_dashboard_freeform_get	publication:read	Read state, URL, version and optional hosting diagnostics
astrato_dashboard_freeform_unpublish	publication:publish	Disable delivery while retaining the current content
astrato_dashboard_freeform_delete	publication:write	Remove a dashboard from the catalog and disable delivery
astrato_management_access_describe	publication:manage-access	Describe supported principals and permissions
astrato_management_access_list	publication:manage-access	List direct user, group and tenant grants
astrato_management_access_grant	publication:manage-access	Create or refresh one direct grant
astrato_management_access_revoke	publication:manage-access	Remove one direct grant

Dashboard metadata and publish-state mutation tools take expectedVersion. Read the dashboard first, pass its returned version, and read it again before retrying if another change causes a version_conflict. Access-grant changes do not change the publication version.

Creation takes an idempotencyKey. Reuse the same key when retrying a request whose result was lost; use a new key for a new target. For content publishing and interrupted uploads, follow the CLI publication workflow.

Each successful publish pins the semantic layer’s current published revision and its data connection. Later semantic-layer changes do not silently change an existing dashboard. Publishing the dashboard again replaces both its current files and pinned data binding. Astrato does not keep deploy history for rollback; restore an earlier revision in your source repository, rebuild it, and publish it again.

Read a dashboard with includeHosting: true to discover available locations, its data-node profile, default location and prerequisite warnings. This also requires read access to its semantic layer. Update hosting with { "mode": "data-node" } to follow the data node, or { "mode": "custom", "deploymentBindingId": "<id-from-hostingStatus.locations>" } to select a returned location. Hosting updates require both manage and publish permissions, plus publication:publish for OAuth in addition to publication:write. Use the current expectedVersion.

Hosting and data access

New publications default to the publication location configured for the data connection’s region. If that location is unavailable, Astrato does not choose another one. Ask your administrator to make the matching location available, or explicitly select another publication location. Choosing a different publication location does not change the data connection’s region.

In Publications → Properties → Publication location, enable Use a different publication location, select an available location, then choose Apply publication location. Turn the option off and apply to return to the data-node default. Changing location requires both manage and publish permission. Files stay in your tenant storage and do not need uploading again. The regional publication address changes; existing regional links may stop working.

The CLI exposes the same choice. Read available locations and the current version first:

astrato publications get <publication-id> --hosting
astrato publications update <publication-id> --publication-node <location-id> --expected-version <version>

Return to default mode with:

astrato publications update <publication-id> --follow-data-node --expected-version <version>

You can also pass --publication-node <location-id> or --follow-data-node to astrato publish. Omitting both keeps the saved mode; a default-mode publish resolves the current data node again. For automation, append --json. OAuth hosting changes require publication:write and publication:publish as well as normal resource permissions.

If the connection’s data node changes while an app is published in default mode, the old location refuses new runtime requests and refreshed file access. Open its properties and apply the default location again, or publish again. Already cached files may remain available until their access expires. Existing data grants retain their normal expiry. Explicitly selected publication locations remain independent of data-node changes.

An enabled, available non-legacy data exit node is always required. If it is disabled, missing, or legacy, open the data connection settings and select a supported exit node. The properties panel and CLI report this prerequisite. Selecting a different publication location cannot bypass it: queries always go directly from your browser to the data exit node, with no legacy fallback.

If an older publication has Use a different publication location turned on, turn it off to follow the data node.

Direct access

The generic Management access tools target this dashboard with resourceType: "dashboard-freeform" and resourceId: <dashboardId>. Their live schemas will add other securable resource types without creating a separate ACL workflow for each product area.

Data App access is explicit. A grant targets one Astrato user, one Astrato group, or the current tenant and grants one of these permissions:

• view — open and inspect the dashboard;
• manage — change its name and labels; combined with publish, change its hosting location;
• publish — publish replacement content or unpublish it;
• manage_access — list, grant and revoke direct access;
• delete — remove the publication and disable its URL.

The creating user receives all five grants. Access follows current group membership. Collection membership does not grant publication access.

An authorized publication session covers all files in that publication. File access is reused for up to five minutes, ending earlier if the session credential expires. Requests do not extend that window. Removing access, unpublishing, deleting or replacing a publication can therefore leave its previously authorized files available for the rest of the window. Signing out ends the publication session immediately. New runtime requests, including issuing data tokens, still check current access; already issued data tokens keep their own expiry.

Data App access does not by itself grant access to the semantic layer or its data. Governed data requests continue to use the signed-in user’s Astrato permissions.

Publication summaries omit Delete when your OAuth grant lacks publication:write, even if your user has delete permission. You can delete a publication from the lobby using your signed-in browser session and delete permission. OAuth authors also need publication:write; viewer consumption grants cannot delete publications, including through the deletion tool. CLI management uses your OAuth login by default, with PAT or browser-session overrides as described in the CLI reference.

Add a published app to a collection

Pass --collection <collection-id> to astrato publish to add the app to a collection after it publishes. You must be able to edit that collection. The app is already live by then, so a refused or failed collection add does not undo the publish. The CLI prints a warning and, with --json, reports the outcome in a collection field. Add the app from the Apps page in that case.

astrato publish ./my-app --publication-id <publication-id> --expected-version <version> --idempotency-key sales-app-publish-1 --collection <collection-id>

In App Builder, the Publish control lists the collections you can edit. Choose one, or No collection, before publishing. A collection you can only view does not appear in the list.

Publication result

A successful publish means Astrato verified and activated the uploaded files. It does not check application loading or data queries. Open the hosted app and exercise its data access separately.

A returned url is the configured canonical address. When it is null, urlUnavailableReason explains whether the publication has no resolved location yet or the location lacks a configured hostname. Ask your administrator to configure a missing hostname; do not guess the app’s address.