How Tokens Work

Hawcx agent tokens are fundamentally different from traditional bearer tokens. They are single-use, pre-minted, and encrypted. This means a stolen token can't be replayed, tokens are ready before the agent needs them, and intercepted tokens are unreadable.

Token Properties

Property	Value	Notes
TTL	60 seconds (default)	Configurable per policy
Usage	Single-use	Consumed on first use, can never be reused
Batch size	10 tokens per batch	Pre-minted before the agent needs them
Queue refill	Automatic	Fresh authentication when tokens run low
Refresh tokens	None	Session renewal = full mutual re-authentication

No refresh tokens

Hawcx does not use refresh tokens. When tokens run low, the system triggers a full mutual re-authentication to establish new session material. This eliminates the long-lived credential attack surface that has been repeatedly exploited in traditional auth systems.

How Pre-Minting Works

The Token Queue Service (TQS) maintains a queue of ready-to-use tokens for each active session:

Batch mint: 10 tokens are minted at once, each with a unique identifier and its own encryption keys
Just-in-time: Tokens are minted seconds before anticipated use, not days in advance
Short TTL: Each token expires in 60 seconds. Even if stolen, the window is tiny.
Auto-refill: When the queue runs low, a fresh authentication handshake is triggered automatically

The Agent's View

From the agent's perspective, tokens are opaque. The agent calls dequeueToken(tool_name) and either gets a token or doesn't:

// The SDK handles all queue management transparently
const token = await agent.dequeueToken("mcp:git_push");

// Present the token with the service request
const response = await agent.fetch("https://api.example.com/deploy", {
  method: "POST",
  body: payload,
});

The agent never sees the token's contents (they're encrypted), never manages TTLs, and never triggers refresh. The token service handles all of this in a separate process.

Token Consumption

Each token is consumed on first use. There is no grace period:

The service extracts the session ID from the token
It checks if this token has been used before (atomic check-and-consume)
If unused: token is valid, proceed with verification
If already used: reject immediately

A consumed token is gone forever.

Session Renewal

When the token queue runs low:

The token service signals that it needs more tokens
A fresh mutual authentication handshake is performed
New session keys are established
New key material is provisioned to the service
A fresh batch of tokens is minted with the new session keys
Old session keys expire via TTL

This provides continuous key rotation and bounds the compromise window to the interval between re-authentications.

Emergency Revocation

For immediate access termination:

Security event signals: Events like credential compromise or policy changes trigger an immediate flush of all pre-minted tokens at the token service
Session invalidation: The service marks the session as revoked, and any in-flight tokens are rejected on arrival
Both happen independently for defense in depth

There is no "revoke a single token" API because tokens are single-use. You either flush the entire queue or invalidate the session.