Skip to content

Written for: For developersUsing Astrato instead? Read the product guide

Authentication for Data Apps and the CLI

4 min read · Updated 17 Nov 2026

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.

The CLI uses OAuth device authorization for interactive use. Start by checking your status:

Terminal window
astrato status

For machine-readable output in automation or an AI-agent workflow, use:

Terminal window
astrato status --json

If the status says you are not authenticated, run:

Terminal window
astrato login

The 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.

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.

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.

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.

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.

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.

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.