Quickstart

This guide gets you from zero to a fully authenticated AI agent in under 10 minutes.

Prerequisites

• A Hawcx account with Agentic Auth enabled (request access)
• Node.js 18+ or Python 3.9+
• An authorized human to complete one-time agent registration via your organization's identity provider

Install the SDK

npm install @hawcx/agent-sdk

pip install hawcx-agent

Register Your Agent

Every agent needs its own identity. Registration is a one-time step where an authorized human enrolls the agent via your identity provider (Hawcx, Okta, Azure AD, Google Workspace, etc.).

import { HawcxAgent } from "@hawcx/agent-sdk";

const agent = new HawcxAgent({
  agentInstanceId: "order-processor-01",
  configId: process.env.HAWCX_CONFIG_ID,
});

// One-time registration (requires human authentication)
await agent.register();

from hawcx_agent import HawcxAgent
import os

agent = HawcxAgent(
    agent_instance_id="order-processor-01",
    config_id=os.getenv("HAWCX_CONFIG_ID"),
)

# One-time registration (requires human authentication)
await agent.register()

That's it. Your agent now has its own cryptographic identity, completely separate from any human user.

Authenticate

Authentication uses a mutual cryptographic handshake. No passwords. No secrets transmitted.

await agent.authenticate();

// Session established. Tokens are pre-minted and ready to use.
const status = await agent.tokenStatus();
console.log(status.queueDepth);  // 10 (tokens ready)
console.log(status.ttl);         // 60 (seconds per token)

await agent.authenticate()

# Session established. Tokens are pre-minted and ready to use.
status = await agent.token_status()
print(status.queue_depth)  # 10 (tokens ready)
print(status.ttl)          # 60 (seconds per token)

Once authenticated, the system immediately pre-mints a batch of 10 single-use tokens, each valid for 60 seconds.

Make Authorized Calls

// Each request automatically uses a single-use token
const response = await agent.fetch("https://api.yourapp.com/orders", {
  method: "GET",
});

// One token per request. More are minted automatically as needed.

# Each request automatically uses a single-use token
response = await agent.fetch("https://api.yourapp.com/orders", method="GET")

# One token per request. More are minted automatically as needed.

Each request consumes exactly one single-use token. The token is encrypted and signed, so even if intercepted, it's unreadable and can't be replayed. When tokens run low, the system re-authenticates and mints more automatically.

What Just Happened

In four steps, your agent now has:

• Its own cryptographic identity, not sharing the deploying user's credentials
• Per-request authorization where each action is scoped by access policy, not broad session permissions
• Single-use encrypted tokens with a 60-second TTL, pre-minted in batches of 10
• A full audit trail with every action logged to the agent's identity, scope, and timestamp

Next Steps

• How Tokens Work to understand how tokens are pre-minted and refreshed
• Permissions & Policies to understand how permissions work per action
• LangChain Example to integrate with LangChain tools