Authentication

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

Agent session (`aas_*`)

Use the agent session for:

official CLI login through browser approval
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

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_*`)

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.

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

Treat it as secret material.

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

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

auth.md agent authentication

Agent Analytics also publishes auth.md discovery metadata so compatible agents can discover the API auth flow from a 401 response instead of asking for a copy-pasted API key.

Live discovery endpoints:

Compatible agents should use the user-claimed browser approval flow. Agent Analytics issues scoped aas_* sessions after human approval; it does not issue raw account API keys to agents.

For details, see auth.md agent authentication.

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] auth status shows whether local CLI auth exists, where config is stored, and which credential store is active without printing token values.
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 saved local CLI auth and revokes the stored agent session when possible.

Use the web app’s Agent Sessions section when you want to inspect active agent sessions or disconnect a specific session from the server without using that client.

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

CLI credential storage

Credential storage is automatic. Normal users do not need to set an environment variable.

macOS and Windows store CLI agent-session secrets in the OS keychain by default.
Linux and headless runtimes use config-file storage by default.
Existing file-stored sessions migrate to native keychain storage on the next authenticated command when native storage is available.
AGENT_ANALYTICS_CREDENTIAL_STORE is only an advanced troubleshooting override. Supported values are auto, native, and file.

Authentication

Agent session (aas_*)