Skip to main content

​
Authentication

Panguard AI uses an OAuth-based authentication flow for CLI sessions, with multiple layers of credential security including AES-256-GCM encryption, TOTP two-factor authentication, and timing-safe API key verification.

​
Authentication Flow Overview

  User
    |
    v
  [panguard.ai]  -- Register / Google OAuth / Email+Password
    |
    | OAuth callback
    v
  [panguard login]  -- Opens browser -> completes auth -> stores token
    |
    | Token at ~/.panguard/credentials.json (0o600)
    v
  [panguard scan / guard / trap ...]  -- Features unlocked by tier

​
CLI Login

​
Standard Flow (With Browser)

1

Start login

panguard login
The CLI starts a temporary HTTP server on a random local port and generates a CSRF state token.
2

Browser authentication

Your default browser opens to panguard.ai/login?cli_state={state}. Complete login via Google OAuth or email and password.
3

Token callback

The server redirects back to the local callback URL. The CLI receives and stores the session token.
4

Session active

The terminal displays a login success message with your account details.
  PANGUARD AI

  -- Login Info ----------------------------------------

  Email     user@example.com
  Name      User Name
  Plan      Solo
  Expires   2026-04-27

  Login successful!

​
Headless Flow (SSH / No Browser)

panguard login --no-browser
The CLI prints an authentication URL that you can copy and open on any device with a browser: 
  Open the following URL in your browser to complete login:
  https://panguard.ai/login?cli_state=abc123&callback=...

  Waiting for authentication...
The --no-browser flag is essential for CI/CD pipelines, Docker containers, and remote servers accessed via SSH.

​
Google OAuth

Panguard supports Google OAuth for one-click sign-in. When you click “Sign in with Google” on the web or during the CLI flow, Panguard receives only your email and display name — no Google password or other account data is accessed.

​
Credential Storage

​
File Location and Permissions

~/.panguard/credentials.json
File permissions are set to 0o600 (owner read/write only) immediately after creation. The CLI verifies these permissions on every startup and warns if they have been loosened.

​
Token Format

{
  "token": "session-token-string",
  "expiresAt": "2026-04-27T00:00:00.000Z",
  "email": "user@example.com",
  "tier": "solo",
  "name": "User Name",
  "savedAt": "2026-02-26T12:00:00.000Z",
  "apiUrl": "https://panguard.ai"
}

​
Session Lifetime

  • CLI sessions are valid for 30 days
  • After expiration, run panguard login again
  • Check expiration with panguard whoami

​
Credentials Encryption

Sensitive configuration fields (API keys, LLM provider tokens) are encrypted at rest using AES-256-GCM:
PropertyValue
AlgorithmAES-256-GCM
Key derivationMachine-specific key from hardware identifiers
Storage~/.panguard/llm.enc for AI provider keys
IVUnique per encryption operation
The encryption key is derived from your machine’s hardware identifiers, so encrypted config files cannot be copied to a different machine and decrypted.

​
TOTP Two-Factor Authentication

Panguard supports TOTP-based 2FA for additional account security.
1

Enable 2FA

Navigate to Account Settings on panguard.ai and select Enable Two-Factor Authentication. Scan the QR code with your authenticator app (Google Authenticator, Authy, 1Password, etc.).
2

Verify setup

Enter a TOTP code from your authenticator app to confirm the setup is working.
3

Save backup codes

Panguard generates 10 single-use backup codes. Store them securely — these are the only way to recover your account if you lose your authenticator device.
4

CLI login with 2FA

Once enabled, the CLI login flow prompts for the TOTP code after browser authentication. The 6-digit code is entered directly in the terminal.
Backup codes are shown only once during 2FA setup. If you lose both your authenticator device and backup codes, account recovery requires contacting support with identity verification.

​
Session Management

​
Logout

panguard logout
Logout performs two actions:
  1. Local — Deletes ~/.panguard/credentials.json
  2. Server-side — Invalidates the session token on the Panguard API server
After logout, the token cannot be reused even if a copy was retained.

​
Verify Session

panguard whoami

# JSON output for scripting
panguard whoami --json

​
Manager API Authentication

The Panguard Manager (fleet orchestration layer) uses Bearer token authentication for its REST API:
PropertyValue
HeaderAuthorization: Bearer <token>
ComparisonSHA-256 timing-safe (crypto.timingSafeEqual)
Rate limitingPer-token, configurable
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://manager.example.com/api/v1/agents
Timing-safe comparison prevents timing attacks that could be used to guess valid tokens character by character.

​
Threat Cloud API Authentication

The Threat Cloud API uses API keys with per-key rate limiting:
PropertyValue
HeaderX-API-Key: <key>
Rate limitPer-key, default 100 requests/minute
Key format64-character hex string
ComparisonSHA-256 timing-safe
curl -H "X-API-Key: YOUR_API_KEY" \
  https://threat.panguard.ai/api/v1/ioc/query?ip=203.0.113.50

​
Security Measures Summary

MeasureDetails
CSRF protectionRandom state token validates the OAuth callback
Callback restrictionOnly localhost callback URLs are accepted
File permissionscredentials.json set to 0o600 on creation
Token expirationSessions auto-expire after 30 days
Flow timeoutPending authentication flows cleaned up after 10 minutes
Encryption at restAES-256-GCM for sensitive config fields
Timing-safe comparisonAll API token verification uses constant-time comparison
2FA supportOptional TOTP with backup codes

​
Common Operations

# Login (opens browser)
panguard login

# Login on headless server
panguard login --no-browser

# Check account info
panguard whoami

# JSON output for scripting
panguard whoami --json

# Logout (local + server-side invalidation)
panguard logout

# Use a custom auth server (development / self-hosted)
panguard login --api-url http://localhost:3100

Account Setup

Create your account and configure your subscription.

System Architecture

How authentication fits into the three-layer platform architecture.