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 session lasts 30 minutes by default, or the policy's maximum session duration (at most 8 hours).

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>]

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

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.

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.