Skip to content
Agent Analytics

Authentication

Agent Analytics uses three different credentials. They serve different jobs and should not be swapped.

Agent session (aas_*)

Section titled “Agent session (aas_*)”

Use the agent session for:

  • official CLI login through browser approval
  • plugin and skill flows that authenticate through the hosted approval flow
  • agent-native setup where the agent should keep the connection after approval

In the normal product flow, you do not paste this token around manually. The hosted approval flow creates it for the agent or CLI and stores it locally for later use.

Managing active agent sessions

Section titled “Managing active agent sessions”

If you want to inspect or revoke agent-owned logins later, open app.agentanalytics.sh and go to Account Settings → Agent Sessions.

That page shows active hosted agent sessions such as:

  • CLI logins
  • macOS Live app connections
  • Paperclip connections
  • MCP or other hosted agent-session clients

Use Disconnect there when you want to revoke one specific session on the server.

API key (aak_*)

Section titled “API key (aak_*)”

Use the API key for:

  • reading analytics data
  • creating or listing projects
  • account-level endpoints
  • direct API access from server-side scripts and tools that cannot use agent sessions

Pass it with the X-API-Key header or the ?key= query parameter.

Terminal window
curl "https://api.agentanalytics.sh/stats?project=my-site&since=7d" \
  -H "X-API-Key: aak_..."

Treat it as secret material.

Project token (aat_*)

Section titled “Project token (aat_*)”

Use the project token for:

  • POST /track
  • POST /track/batch
  • the browser tracker snippet embedded on your site

The token is public by design. It identifies the project for event ingestion and is expected to appear in HTML.

<script defer src="https://api.agentanalytics.sh/tracker.js"
        data-project="my-site"
        data-token="aat_..."></script>

Common mistake

Section titled “Common mistake”

Do not put the API key in the client-side tracker. The tracker uses the public project token only.

CLI auth helpers

Section titled “CLI auth helpers”

If you use the official CLI, it provides browser-approved local auth helpers:

  • npx --yes @agent-analytics/[email protected] login starts browser approval and saves a local CLI session.
  • npx --yes @agent-analytics/[email protected] login --detached starts the same flow for headless or issue-based runtimes where the agent sends you an approval link and may ask for a finish code.
  • npx --yes @agent-analytics/[email protected] upgrade-link --detached prints a human-owned Pro payment handoff when a free account hits a paid-only analytics task.
  • npx --yes @agent-analytics/[email protected] logout clears the saved local CLI auth.

logout is local-only for CLI state. If you want to revoke the hosted session itself, disconnect that session from the web app’s Agent Sessions section.

Scoped agent sessions cannot generate or rotate raw account API keys. Manage compatibility API keys from the dashboard.

If you set AGENT_ANALYTICS_API_KEY in your shell environment, the CLI will continue to use that env var even after logout until you unset it.

Section titled “Related”