Agent Dashboard Sign-In

An owner can let one of their agents sign in to the owner's AstraSync dashboard and work there with the owner's access — narrowed by the agent's policy. The session is tied to one machine in the organisation's fleet, signs in through the agent's Workforce Guard checkpoint, and waits for the owner's passkey wherever the policy asks.

Before you start

• Workforce Guard is set up for your organisation, and the agent runs through a Workforce Guard checkpoint (you'll need the checkpoint's public URL and the agent's slug on it).
• The agent's machine is enrolled in your organisation's fleet (see step 2). The machine must be enrolled in the organisation that owns the agent.
• AstraSync's own site policy already includes the sign-in route — there is nothing for you to configure on that side.

1. Turn on Dashboard access in the agent's policy

Dashboard access is off for every agent until you allow it. Because an agent's policy is fixed per version, you turn it on with Upgrade (agent page → Upgrade): this issues a new version with a new ASTRA-id and retires the old one. The agent's Workforce Guard checkpoint follows it to the new version, at the same URL.

In the policy editor, switch on Dashboard access. The defaults are:

• Ask me before it signs in — on.
• Ask me before any change — on.
• Reads don't ask.
• Read-only (no changes at all) — optional.

Under the hood these are ordinary policy actions — dashboard.signin, dashboard.read and dashboard.change — on resources named dashboard:<area> (for example dashboard:agents, dashboard:endpoints, dashboard:visit-intelligence). Narrow the agent to particular areas with dashboard:<area> entries under Scope. The owner's sign-in approval lasts 30 minutes by default, or the policy's maximum session duration (at most 8 hours); each session token lasts at most 30 minutes of it and is renewed (see Renewing a session).

2. Enrol the agent's machine

Use an enrolment token from Enterprise Governance → Fleet. Two options:

# One user on this machine (default) — no administrator rights needed
astrasync guard enroll <token>

# The whole machine (typically pushed by MDM) — needs administrator rights
astrasync guard enroll <token> --system

3. Sign in with astrasync guard browse

astrasync guard browse \
  --checkpoint <checkpoint public URL> \
  --slug <the agent's checkpoint slug> \
  [--upstream <AstraSync API upstream slug, default astrasync-api>] \
  [--port <local proxy port>] \
  [--host <extra host that should get the device credential>] \
  [--open]

The command:

1. Starts a local proxy. It adds this machine's device credential to requests for the AstraSync hosts only; every other host is passed through as a blind tunnel. The browser never holds the credential.
2. Signs in through the agent's Workforce Guard checkpoint, which verifies the agent and runs the runtime challenge.
3. If the policy asks, waits for the owner to approve the sign-in with their passkey — one approval, shown as a dashboard sign-in in Activity → Pending Verifications.
4. Prints a one-time sign-in URL. Open it in the browser through the proxy within 2 minutes (the code is valid for 120 seconds and works once).

Open the link yourself

The link doesn't work in your everyday browser: it must go through the proxy. Add --open and the command starts Chrome, Edge or Chromium through the proxy, on its own profile, as soon as the sign-in is approved. On WSL it prefers a Chromium installed inside WSL — a Windows browser may not reach the proxy there; install one with npx playwright install chromium.

Without --open, the command prints a browser command to paste (PowerShell on Windows and WSL). It includes the proxy port and the fingerprint of the proxy's local certificate, so the browser trusts that one certificate and checks every other site as usual. Chrome shows a warning bar about that flag; that's expected, so close it. The command looks like this:

# macOS / Linux
google-chrome --proxy-server="http://127.0.0.1:<port>" \
  --ignore-certificate-errors-spki-list=<fingerprint> \
  --user-data-dir="/tmp/astrasync-agent" '<the one-time sign-in URL>'

# Windows (PowerShell)
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --proxy-server="http://127.0.0.1:<port>" --ignore-certificate-errors-spki-list=<fingerprint> --user-data-dir="$env:TEMP\astrasync-agent" '<the one-time sign-in URL>'

Opening the proxy address (http://127.0.0.1:<port>) directly shows a short page saying it only works as a browser proxy.

For a Playwright-driven browser, point it at the proxy the command prints:

const browser = await chromium.launch({ proxy: { server: 'http://127.0.0.1:<port>' } });
const context = await browser.newContext({ ignoreHTTPSErrors: true }); // the proxy's local certificate
const page = await context.newPage();
await page.goto('<the one-time sign-in URL>');

Keep the command running for the whole session; Ctrl-C stops the proxy.

Bound to the machine

Every request in the session must carry that machine's device credential. The session ends when:

• a request arrives without the device credential, or from another machine;
• the device is revoked in the fleet;
• the owner signs out everywhere;
• the owner presses End session;
• it reaches its lifetime.

Renewing a session

A session token lasts at most 30 minutes, but the owner's passkey approval lasts the policy's maximum session duration (never past the policy's end time or end date). Within that window the agent renews without asking the owner again: POST /api/agent-sessions/<sessionId>/renew, sent like sign-in through the agent's checkpoint (a verified agent that answers its runtime challenge, from the same machine; add the route to the site's route policy with action dashboard.signin). The answer is the same as redeeming a sign-in code — a new sessionId, expiresAt, approvalExpiresAt and session cookies — and the old token stops working. The agent's current policy is checked again each time, so a suspended agent, a narrowed policy or a closed window stops renewal, and so does End session. Once the approval has run out the answer is 403 approval_expired: sign in again for a new approval.

What the agent can and can't do

• Reads go through, within the areas the policy allows.
• Changes wait for the owner's approval of that exact request (method, path, query and body) when the policy asks. The API answers 202 OWNER_APPROVAL_REQUIRED with an approvalId; the dashboard shows a waiting dialog and retries once after the owner approves. An approval covers that one request only.
• Admin pages are available only when the owner is a superadmin, and every request there — reads too — waits for the owner's passkey.
• Always forbidden, whatever the policy says: deciding approvals, the sign-in and account-security routes (/auth/*), passkeys, minting or rotating any key, token or credential, verify-access, and internal routes. Anything the dashboard doesn't map to an area is refused too.

Seeing and ending sessions

• While an agent is signed in, the dashboard shows a banner. The /agent-session page shows the session.
• The owner sees live and recent sessions in the sessions panel on the agent's page, with End session.
• Sign-ins, held requests, changes and endings are recorded in the activity log.

Common refusals

• DEVICE_CREDENTIAL_REQUIRED — the request didn't come from an enrolled machine (run astrasync guard browse).
• DEVICE_NOT_IN_ORG — the machine is revoked or enrolled in a different organisation from the agent's.
• AGENT_SESSION_DENIED — the agent's policy doesn't allow dashboard sign-in (turn on Dashboard access with Upgrade).
• AGENT_NOT_ACTIVE — the agent is retired, suspended or not yet approved.
• AGENT_SESSION_FORBIDDEN — the route is never available to an agent session.
• approval_expired — renewal refused: the sign-in approval ran out, the session ended, or the agent's policy no longer allows sign-in. Sign in again.