Written for: For developersUsing Astrato instead? Read the product guide
Authentication for Data Apps and the CLI
This page is for developers building Data Apps or scripting against Astrato. Signing in, recovering access, enterprise connections and personal access tokens are in Authentication.
Astrato CLI device authorization
Section titled “Astrato CLI device authorization”The CLI uses OAuth device authorization for interactive use. Start by checking your status:
astrato statusFor machine-readable output in automation or an AI-agent workflow, use:
astrato status --jsonIf the status says you are not authenticated, run:
astrato loginThe CLI prints a URL and code, opens the Astrato approval page when possible, and waits. Complete
the approval in your browser. Access credentials remain in process memory, while the renewable
login is stored in the operating system credential store—never in astrato.json, authored code,
environment files, or CLI output.
For local app development, the CLI requests profile to discover your tenant, schema:read for
semantic-layer metadata and data:query for queries. These scopes do not grant access to a semantic
layer you cannot otherwise use. Your app accesses these operations through @astrato-io/app-runtime,
not by sending OAuth credentials from browser code.
For AI agents
Section titled “For AI agents”An AI agent must not automate login, handle the device code, request a token/PAT/cookie, or inspect
the credential store. It should ask the user to run astrato login, wait for confirmation, and then
re-check astrato status --json. See the CLI reference for the exact checkpoint.
The CLI requests local runtime and publication authoring scopes, subject to your Astrato permissions. Its OAuth credentials stay in the CLI and are never sent to authored browser code. Existing logins without the authoring scopes require fresh approval.
Data App session
Section titled “Data App session”A Data App calls createAstratoApp() from @astrato-io/app-runtime. During local
development, the CLI owns the browser origin, creates a per-run
local Data App session, and exposes only the versioned /_astrato/v1/* runtime boundary.
import { createAstratoApp } from '@astrato-io/app-runtime';
async function start(): Promise<void> { const app = await createAstratoApp(); // Use app.client and app.dataBinding from here.}
start().catch((error) => console.error(error));The runtime bootstraps the tenant, configured semantic layer, datasource type and supported operations from the current origin. It manages the SDK transport and CSRF lifecycle. Authored code must not configure or store a PAT, tenant ID, semantic-layer ID, datasource ID, App API host, session cookie, or CSRF token.
The runtime values returned in app.context and app.dataBinding may be used for current SDK and
visualization calls. Do not copy them into source code or configuration. See the
Data App runtime reference.
The browser same-origin rule
Section titled “The browser same-origin rule”Astrato APIs do not allow direct browser requests from third-party origins. Supplying a PAT does not bypass this rule.
- An externally hosted app calls its own origin and uses its own trusted server or development proxy for Astrato access.
- A local Data App uses the CLI’s same-origin adapter through
@astrato-io/app-runtime. - A published Data App reads its model and obtains a short-lived data token, then calls the explicitly selected data exit node directly. The node must permit that browser origin through its configured CORS policy.
Do not copy the external-app proxy into a Data App, and do not use the Data App runtime in an externally hosted app.
SDK behavior
Section titled “SDK behavior”The general SDK does not sign users in, refresh credentials, or retry automatically after an
authentication failure. Externally hosted code supplies its trusted authentication through the SDK
transport. Data App code does not configure SDK authentication; createAstratoApp()
returns the configured client.
MCP clients and the Astrato CLI implement their own documented OAuth flows outside the SDK.
Hosted publication sign-in
Section titled “Hosted publication sign-in”An enabled hosted Data App redirects you to Astrato to sign in and then returns to its own URL. It requests permission to read app publications and semantic-layer metadata and to query data. These grants do not allow it to create, publish or change access to publications. The app receives an opaque session cookie; it does not receive the main OAuth access or refresh token. It does receive a short-lived data-access token for the selected exit node. Astrato governs that token’s permissions, including writeback and export. Publication access is checked before issuance and renewal; existing data tokens keep their expiry. An OAuth credential issued for MCP or a different Astrato origin cannot open a hosted app.
Your publication access is checked on each file and runtime request. Hosted browser-IP restrictions are not enforced in the current preview. Hosted sessions currently expire after at most five minutes; reopen the app to sign in again. See hosted app sessions.
To sign people in to embedded Astrato content from your own product, with single sign-on or OEM web tickets, see Sign your own users in.
Publication management credentials
Section titled “Publication management credentials”The CLI’s publish and publications commands use the saved OAuth login by default. Authoring
requires publication:read, publication:write and publication:publish on the CLI grant.
An explicit PAT or browser session overrides that login. Cookie mutations retain CSRF protection;
OAuth and PAT requests use bearer authentication. All methods remain subject to publication ACLs.
OAuth deletion requires publication:write and the user’s delete permission. Viewer consumption
grants do not contain that scope. See CLI publishing
for secure credential input and the supported workflow.