Authentication

Authentication depends on the caller and, for browser apps, on which app model applies. Choose the delivery model before copying an authentication example: an externally hosted app and a Data App do not share the same browser bootstrap.

To invite people into your workspace, see Invitation links.

Examples use https://app.astrato.io, the default Astrato application and API host. If your organization supplies another Astrato origin, substitute it where server-side or CLI commands accept a host. Authored Data App code does not configure that origin.

Accept a workspace membership transfer

If you already belong to another workspace, pending invitations appear in the new lobby’s Membership transfer invite dialog. Select the destination if you have several invitations, then choose Accept, or Reject (Reject All for several invitations) to stay in your current workspace.

Transferring removes access to your current workspace and deletes your workbooks. If you own that workspace, select another active user to receive ownership. If no eligible user is available, accepting deletes your current workspace and all its data; enter your account’s email address to confirm. The address must match exactly, including whitespace. If you paste, drag, or automatically fill it, manually edit it before accepting; only typing and deletion count as manual editing. After acceptance, the page reloads with your new membership.

If workspace ownership is transferred but accepting the invitation fails, Reject and Reject All are unavailable. Retry Accept to finish joining the destination workspace; the completed ownership transfer is not repeated or undone.

Enterprise connections

Owners and administrators can open Administration → Enterprise Connection to inspect login connections, access integrations and identity federation. Provider names identify the service, such as Okta or Snowflake; the tabs identify how you use it. Each tab lists only connections of its own type: a Google Workspace login connection appears under login connections, not access integrations.

The Status column shows Enabled once a connection is verified and Not enabled until then. A connection that is not enabled cannot be used yet. Status is Unknown when the provider does not report a verification result.

Select a connection to edit its name and setup fields, replace its client secret or delete it. The panel never displays client secrets or signing keys. To verify a connection, choose Verify in connection settings, which opens that connection in connection settings.

Choose Add connection, Add integration or Add provider to create one in connection settings. A workspace can have only one login connection, so Add connection is unavailable once one exists. Connection settings also handle role and group synchronization and access-token invalidation.

An empty login list does not mean your workspace has no access integrations or federated identity providers. Check the other tabs. If a read fails, the overview reports that failure instead of claiming there are no providers. Invalid provider metadata and responses in an unexpected format are also reported as failed reads.

Which mechanism applies

Caller or environment	Mechanism
Astrato CLI on a developer computer	OAuth device authorization; renewable login stored in the OS credential store
Data App during local development	@astrato-io/app-runtime through the CLI-owned origin and local App session
Externally hosted app’s trusted backend or proxy	PAT bearer header
Externally hosted app during local development	Local trusted proxy that adds a PAT server-side
Externally hosted app delivered to other users	Its own backend/session design; never a PAT shipped in browser code
Server-side script or curl	PAT bearer header
MCP client	MCP OAuth or PAT; see MCP setup

CLI OAuth and MCP OAuth are separate grants for separate clients and scopes. Logging into one does not authenticate the other.

OAuth bearer requests do not use a browser-session CSRF token: the caller explicitly supplies its authorization. Browser sessions still need CSRF protection, including the local Data App session managed by the runtime. Neither mechanism bypasses your data permissions or the OAuth scopes granted to the client.

Review OAuth connections

User Settings presents personal access tokens, OAuth connections and data access in consistent table sections. When your tenant allows PAT creation and your role has permission, use New token in the personal access tokens toolbar to create a token.

In the new UI, open your account menu and choose User Settings → OAuth connections.

You can review apps with active OAuth access in your current tenant, including renewable connections whose short-lived access token has expired. Each entry shows the client name and ID, audiences, granted scopes and Last used. Activity is estimated from the most recent token issuance, including refreshes, and shown as “Within the last hour”, a number of hours or days ago, or “Over a month ago”. It does not prove that the app made a subsequent request. Not recorded means no issuance timestamp is available.

Credentials are never displayed. If a client name is no longer available, its client ID identifies the connection.

Choose Revoke access, review the app named in the confirmation, then choose Revoke. This revokes all existing access and refresh tokens for that app under your account in the current tenant. The app must authorize again to reconnect. Access in other tenants, personal access tokens, browser sessions and data-provider credentials are unaffected.

After successful revocation, the entry disappears. If the request fails, the entry and confirmation remain so you can retry. A failed list request shows an error rather than an empty list. Expired and revoked connections are not shown as history.

Astrato CLI device authorization

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

astrato status

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

astrato status --json

If the status says you are not authenticated, run:

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.

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

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.

Personal Access Tokens

A PAT is a bearer token associated with an Astrato account. Requests made with it use the account’s permissions in the tenant. A PAT is appropriate for trusted server-side code, scripts, MCP clients that do not use OAuth, and an externally hosted app’s private development proxy.

• Create: open user settings in Astrato and choose an expiry in days. PATs do not renew automatically.
• Enable creation: administrators control whether new PATs can be created and which roles may create them. When creation is unavailable, New token and its form are hidden. You can still open the PAT section to review and revoke existing tokens; if you have none, the PAT menu item and section are hidden.
• Revoke: delete a PAT from user settings to invalidate it immediately.

Set ASTRATO_TOKEN without placing its value in shell history. In Bash or zsh, read it without terminal echo and then export it:

printf 'Astrato PAT: '
IFS= read -r -s ASTRATO_TOKEN
printf '\n'
export ASTRATO_TOKEN

Then use it as a bearer header only from trusted code:

curl --config - <<EOF
url = "https://app.astrato.io/api/..."
header = "Authorization: Bearer ${ASTRATO_TOKEN}"
silent
show-error
EOF

The shell expands the variable into curl’s standard input rather than its process arguments. Unset it when you no longer need it.

For independent local browser development, keep the PAT in the development server and have a same-origin proxy add the header. The externally hosted app quickstart shows the Vite configuration. Keep that proxy bound to localhost: anyone who can reach it can make requests with the configured PAT.

A PAT is not multi-user browser authentication. It acts with its owner’s authority and must never be embedded in JavaScript, HTML, a static build, astrato.json, or a page delivered to other users. An externally hosted production app must own a trusted backend/session boundary appropriate to its users. Astrato does not provide that boundary for externally hosted apps.

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

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

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.

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.