API Reference
SDK methods and token service interface
Architecture
Hawcx Agentic Auth uses three components. The agent interacts with its local token service, not a REST API:
| Component | Role | How your agent talks to it |
|---|---|---|
| Authentication Service (AS) | Handles mutual authentication, provisions session material | SDK handles this internally |
| Token Queue Service (TQS) | Pre-mints single-use tokens, enforces access policies | Local IPC (3 methods below) |
| Resource Server (RS) | Verifies tokens, executes authorized actions | Standard HTTPS with token header |
SDK Methods
agent.register()
One-time registration. Requires human authentication via your identity provider.
await agent.register();What happens behind the scenes: The agent's cryptographic identity is created and bound to the human's organizational role and access policies.
agent.authenticate()
Establishes a session via mutual cryptographic handshake. Call this at the start of each session.
await agent.authenticate();What happens behind the scenes: A secure session is established. Session material is provisioned to both the token service and the resource server.
agent.fetch(url, options)
Makes an authenticated request. The SDK automatically attaches a single-use token.
const response = await agent.fetch("https://api.example.com/orders", {
method: "GET",
});What happens behind the scenes: The SDK dequeues one pre-minted token from the token service and attaches it to the request.
agent.ensureAuthenticated()
Registers on first call, re-authenticates if the session has expired. Convenience method for long-running agents.
await agent.ensureAuthenticated();Token Service Interface
The agent's only interface to its token service is three methods:
dequeueToken(tool)
Gets a single pre-minted token scoped to the specified tool.
const token = await agent.dequeueToken("mcp:git_push");| Parameter | Type | Description |
|---|---|---|
tool | string | Tool identifier (e.g., mcp:git_push, a2a:invoice_lookup) |
Returns: An opaque encrypted token (the agent cannot read its contents).
Errors:
- Queue empty (session renewal in progress)
- Policy deny (access policy rejected this tool for this agent)
tokenStatus()
Returns current queue status.
const status = await agent.tokenStatus();| Field | Type | Description |
|---|---|---|
queueDepth | number | Tokens remaining in queue |
ttl | number | TTL of next token (seconds) |
sessionActive | boolean | Whether a session is established |
renewalPending | boolean | Whether re-authentication is in progress |
sessionInfo()
Returns session metadata.
const info = await agent.sessionInfo();| Field | Type | Description |
|---|---|---|
sessionId | string | Current session identifier |
agentInstanceId | string | Agent identifier |
establishedAt | string | ISO 8601 timestamp |
algorithmSuite | number | Negotiated cryptographic suite (1-4) |
Emergency Revocation
Security Event Flush
Security events (credential compromise, policy change) trigger an immediate flush of all pre-minted tokens.
Session Invalidation
The resource server marks the session as revoked. Any in-flight tokens are rejected on presentation.
Both mechanisms operate independently. There is no "revoke a single token" API because tokens are single-use.
Verification
The resource server runs a multi-step verification on every token. Target latency is under 400 microseconds.
The verification process runs automatically on every token presentation.