Authentication

Agent History supports multiple authentication methods for different use cases.

Authentication Methods

Method	Header Format	Use Case
Tempo CLI	`Authorization: Payment <credential>`	Agents via `tempo request`
Tempo Passkey	`Authorization: Tempo <credential>`	Humans via WebAuthn (Face ID, Touch ID)
Agent Key	`Authorization: Bearer aht_live_...`	Direct API access from your agent
Wallet Signature	`Authorization: Signature <sig>`	LOCAL mode operations

Agent Key (Bearer Token)

Agent keys are the primary authentication method for API access. You receive an agent key when you create an agent.

curl -X POST https://agenthistory.ai/api/v1/records/rec_xxx/remember \
  -H "Authorization: Bearer aht_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers dark mode", "type": "fact"}'

Agent Key Format

Agent keys follow this format:

aht_live_... - Production keys
aht_test_... - Test/development keys

Security: Store your agent key securely. Never expose it in client-side code or public repositories.

Tempo CLI (For Agents)

The recommended way for AI agents to authenticate is via the Tempo CLI. This handles wallet setup, payments, and authentication automatically.

Setup Tempo for Your Agent

Paste this into your AI agent to set up Tempo Wallet and start making paid requests:

claude -p "Read https://tempo.xyz/SKILL.md and set up tempo"

amp --execute "Read https://tempo.xyz/SKILL.md and set up tempo"

codex exec "Read https://tempo.xyz/SKILL.md and set up tempo"

Making Requests

Once set up, use tempo request to make authenticated API calls:

# Tempo handles authentication and payments automatically
tempo request -X POST \
  --json '{"content": "User prefers dark mode", "type": "fact"}' \
  https://agenthistory.ai/api/v1/records/rec_xxx/remember

How It Works

Tempo CLI discovers the service pricing
Creates a payment session (deposits pathUSD)
Signs requests with your agent's wallet
Includes payment credential in Authorization: Payment header
Agent History verifies payment and processes request

Learn more at docs.tempo.xyz/cli

Tempo Passkey (For Humans)

For human users in the dashboard, we support Tempo passkey authentication. This uses WebAuthn (Face ID, Touch ID, Windows Hello) for secure, passwordless sign-in.

How Passkeys Work

Biometric auth - Use Face ID, Touch ID, or fingerprint
No passwords - Keys stored in device secure enclave
Cross-device sync - Via iCloud Keychain or Google Password Manager
Domain-bound - Credentials only work on agenthistory.ai

Embedding Passkeys in Your App

If you're building a web app that uses Agent History, you can embed Tempo passkey authentication using viem/tempo:

import { Account, WebAuthnP256 } from 'viem/tempo'

// Create a new passkey
const credential = await WebAuthnP256.createCredential({
  label: 'My App'
})

// Create account from credential
const account = Account.fromWebAuthnP256(credential)

console.log('Address:', account.address)

// Store credential.publicKey in your database for future sign-ins

import { Account, WebAuthnP256 } from 'viem/tempo'

// Sign in with existing passkey
const credential = await WebAuthnP256.getCredential({
  async getPublicKey(cred) {
    // Fetch from your database by credential ID
    const response = await fetch(`/api/passkeys/${cred.id}`)
    const data = await response.json()
    return data.publicKey
  }
})

// Create account from credential
const account = Account.fromWebAuthnP256(credential)

function SignIn() {
  const [account, setAccount] = useState(null)

  const createPasskey = async () => {
    const credential = await WebAuthnP256.createCredential({ label: 'My App' })
    const account = Account.fromWebAuthnP256(credential)
    // Store credential.publicKey in your backend
    setAccount(account)
  }

  const signIn = async () => {
    const credential = await WebAuthnP256.getCredential({
      getPublicKey: async (cred) => fetchPublicKey(cred.id)
    })
    setAccount(Account.fromWebAuthnP256(credential))
  }

  if (account) return <div>Connected: {account.address}</div>

  return (
    <div>
      <button onClick={createPasskey}>Create Passkey</button>
      <button onClick={signIn}>Sign In</button>
    </div>
  )
}

Learn more at viem.sh/tempo/accounts

Wallet Signature (LOCAL Mode)

In LOCAL mode, you can authenticate using an Ethereum wallet signature. This is useful for self-custody scenarios.

import { AgentHistoryClient } from '@agenthistory/sdk'

const client = new AgentHistoryClient({
  mode: 'local',
  wallet: {
    address: '0x1234...abcd',
    signMessage: async (message) => {
      // Use your wallet provider to sign
      return await wallet.signMessage(message)
    },
  },
})

Signature Format

The signature header contains a signed message proving wallet ownership:

Authorization: Signature <timestamp>:<walletAddress>:<signature>

Fee-Sponsored Endpoints

Some endpoints are fee-sponsored and don't require payment credentials:

POST /api/v1/agents - Create agent
POST /api/v1/records - Create record
GET /api/v1/records - List records
GET /api/v1/records/[id] - Get record
PATCH /api/v1/records/[id] - Update record
DELETE /api/v1/records/[id] - Delete record

See Pricing for full details on which operations are free vs paid.