H33 Quickstart:
Your First Authentication in 5 Minutes

Most authentication systems are built on cryptography that a sufficiently powerful quantum computer could break. RSA, ECDSA, and the key exchanges behind TLS all rely on mathematical hardness assumptions — integer factorization and discrete logarithms — that Shor's algorithm renders trivial on quantum hardware. The threat is not theoretical. Nation-states are already conducting harvest-now-decrypt-later attacks, storing encrypted traffic today for decryption when quantum computers mature.

H33 solves this with a single API that combines three cryptographic primitives into one authentication call: Fully Homomorphic Encryption (FHE) for biometric matching on encrypted data, zero-knowledge proofs for privacy-preserving verification, and post-quantum signatures (CRYSTALS-Dilithium) for tamper-proof attestation. The entire pipeline completes in approximately 50 microseconds per authentication — faster than a single database round-trip.

This guide walks you through every step: creating your account, installing the SDK in your preferred language, enrolling your first user, running your first verification, inspecting the attestation response, and hardening your integration for production. By the end, you will have a working, quantum-resistant authentication flow that you can deploy today.

Prerequisites

Before you begin, make sure you have the following:

• An H33 account — sign up at h33.ai/get-api-key (free tier, no credit card)
• A terminal with curl installed (macOS, Linux, or WSL on Windows)
• One of the supported runtimes: Node.js 18+, Python 3.9+, Go 1.21+, or Rust 1.75+
• Basic familiarity with REST APIs — we will use JSON over HTTPS throughout

Step 1: Get Your API Key

Navigate to h33.ai/get-api-key and create an account. After email verification, the dashboard presents your API key. It will look like this:

h33_live_pk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Keys prefixed with h33_live_ hit the production API. Keys prefixed with h33_test_ hit the sandbox environment, which returns deterministic results for integration testing. Both environments support the full API surface — the only difference is that sandbox responses are not cryptographically valid.

Set the key as an environment variable now. Every code example in this guide references it:

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export H33_API_KEY="h33_live_pk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

# Verify it's set
echo $H33_API_KEY

Step 2: Install the SDK

H33 provides official SDKs for four languages. Each SDK wraps the REST API with type-safe methods, automatic retry logic, connection pooling, and built-in attestation verification. You can also call the REST API directly with curl or any HTTP client — no SDK is required.

npm install @h33/sdk

pip install h33

go get github.com/h33-ai/h33-go

cargo add h33

All SDKs are open source. The Node.js and Python SDKs are the most widely adopted in production, but the Go and Rust SDKs are feature-complete and follow the same release cadence.

Step 3: Initialize the Client

Initialize the H33 client with your API key and (optionally) specify a region, timeout, and retry policy. The client handles TLS certificate pinning, connection pooling, and automatic failover internally.

Node.js

import { H33Client } from '@h33/sdk';

const h33 = new H33Client({
  apiKey: process.env.H33_API_KEY,
  region: 'us-east-1',       // optional: us-east-1, eu-west-1, ap-southeast-1
  timeout: 5000,             // optional: request timeout in ms (default 10000)
  retries: 3,               // optional: automatic retries on 5xx (default 2)
});

// Verify connectivity
const status = await h33.health();
console.log(status);
// { ok: true, region: "us-east-1", latency_ms: 12 }

Python

import os
from h33 import H33Client

client = H33Client(
    api_key=os.environ["H33_API_KEY"],
    region="us-east-1",
    timeout=5.0,
    retries=3,
)

# Verify connectivity
status = client.health()
print(status)
# {"ok": True, "region": "us-east-1", "latency_ms": 14}

Go

package main

import (
    "fmt"
    "os"
    h33 "github.com/h33-ai/h33-go"
)

func main() {
    client, err := h33.NewClient(h33.Config{
        APIKey:  os.Getenv("H33_API_KEY"),
        Region:  "us-east-1",
        Timeout: 5 * time.Second,
    })
    if err != nil {
        panic(err)
    }

    status, _ := client.Health(context.Background())
    fmt.Println(status)
}

curl (No SDK)

curl -s https://api.h33.ai/v1/health \
  -H "Authorization: Bearer $H33_API_KEY" | jq .

# Response
{
  "ok": true,
  "region": "us-east-1",
  "latency_ms": 8,
  "api_version": "v1",
  "pq_algorithms": ["dilithium3", "dilithium5", "kyber768", "falcon512"]
}

Step 4: Enroll Your First User

Enrollment is the process of registering a user's biometric template with H33. The template is encrypted client-side under FHE before it leaves the user's device — H33's servers never see the raw biometric data. The encrypted template is stored, and a unique enrollment_id is returned for subsequent verification requests.

Enrollment accepts a 128-dimensional feature vector (the output of your biometric capture SDK, face encoding model, or fingerprint minutiae extractor). H33 encrypts this vector into a BFV ciphertext and stores the encrypted template. You only need to enroll a user once — the template persists until you explicitly delete it.

Enrollment with curl

curl -X POST https://api.h33.ai/v1/auth/enroll \
  -H "Authorization: Bearer $H33_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_jane_doe_001",
    "biometric_vector": [0.0234, -0.1892, 0.4521, 0.0012, ...],
    "modality": "face",
    "metadata": {
      "device": "iPhone 15 Pro",
      "capture_quality": 0.97,
      "liveness_score": 0.99
    }
  }'

# Response
{
  "enrollment_id": "enr_8xKm3Qf2vR7nL9pW",
  "user_id": "user_jane_doe_001",
  "modality": "face",
  "template_encrypted": true,
  "encryption_scheme": "BFV-4096",
  "created_at": "2026-01-16T14:32:01Z",
  "attestation": {
    "algorithm": "dilithium3",
    "signature": "base64...",
    "public_key": "base64..."
  }
}

Enrollment with Node.js

const enrollment = await h33.auth.enroll({
  userId: 'user_jane_doe_001',
  biometricVector: faceEmbedding,    // Float64Array, 128 dimensions
  modality: 'face',
  metadata: {
    device: 'iPhone 15 Pro',
    captureQuality: 0.97,
    livenessScore: 0.99,
  },
});

console.log(enrollment.enrollmentId);
// "enr_8xKm3Qf2vR7nL9pW"

console.log(enrollment.templateEncrypted);
// true — biometric never leaves your device in plaintext

Enrollment with Python

import numpy as np

# face_embedding: np.ndarray of shape (128,) from your capture pipeline
enrollment = client.auth.enroll(
    user_id="user_jane_doe_001",
    biometric_vector=face_embedding.tolist(),
    modality="face",
    metadata={
        "device": "iPhone 15 Pro",
        "capture_quality": 0.97,
        "liveness_score": 0.99,
    },
)

print(enrollment.enrollment_id)
# "enr_8xKm3Qf2vR7nL9pW"

Enrollment with Go

enrollment, err := client.Auth.Enroll(ctx, &h33.EnrollRequest{
    UserID:          "user_jane_doe_001",
    BiometricVector: faceEmbedding,   // []float64, len 128
    Modality:        "face",
    Metadata: map[string]interface{}{
        "device":          "iPhone 15 Pro",
        "capture_quality": 0.97,
        "liveness_score":  0.99,
    },
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(enrollment.EnrollmentID)
// "enr_8xKm3Qf2vR7nL9pW"

The response includes an attestation object containing a CRYSTALS-Dilithium signature over the enrollment event. This signature proves that the enrollment was processed by H33 infrastructure at the stated timestamp. You can verify this attestation independently using any Dilithium library — no trust in H33 is required for verification.

Step 5: Verify Your First Authentication

Verification is the core operation. You submit a fresh biometric capture, H33 matches it against the enrolled template under FHE, generates a zero-knowledge proof that the match was computed correctly, and returns a post-quantum signed attestation of the result. The entire pipeline completes in approximately 50 microseconds per authentication at production scale.

Verification with curl

curl -X POST https://api.h33.ai/v1/auth/verify \
  -H "Authorization: Bearer $H33_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_jane_doe_001",
    "biometric_vector": [0.0229, -0.1901, 0.4498, 0.0018, ...],
    "modality": "face",
    "threshold": 0.85,
    "require_attestation": true
  }'

# Response
{
  "verified": true,
  "confidence": 0.9847,
  "user_id": "user_jane_doe_001",
  "latency_us": 48,
  "pipeline": {
    "fhe_match_us": 31,
    "zkp_verify_us": 8,
    "attestation_us": 9
  },
  "attestation": {
    "algorithm": "dilithium3",
    "signature": "base64...",
    "public_key": "base64...",
    "payload_hash": "sha3_256:9f86d081...",
    "timestamp": "2026-01-16T14:33:07Z"
  }
}

Verification with Node.js

const result = await h33.auth.verify({
  userId: 'user_jane_doe_001',
  biometricVector: freshCapture,     // Float64Array from camera/sensor
  modality: 'face',
  threshold: 0.85,
  requireAttestation: true,
});

if (result.verified) {
  console.log(`Authenticated in ${result.latencyUs}µs`);
  console.log(`Confidence: ${result.confidence}`);
  console.log(`Attestation sig: ${result.attestation.signature}`);
} else {
  console.log('Verification failed');
}

Verification with Python

result = client.auth.verify(
    user_id="user_jane_doe_001",
    biometric_vector=fresh_capture.tolist(),
    modality="face",
    threshold=0.85,
    require_attestation=True,
)

if result.verified:
    print(f"Authenticated in {result.latency_us}µs")
    print(f"Confidence: {result.confidence}")
    print(f"Algorithm: {result.attestation.algorithm}")
else:
    print("Verification failed")

Verification with Go

result, err := client.Auth.Verify(ctx, &h33.VerifyRequest{
    UserID:             "user_jane_doe_001",
    BiometricVector:    freshCapture,
    Modality:           "face",
    Threshold:          0.85,
    RequireAttestation: true,
})
if err != nil {
    log.Fatal(err)
}

if result.Verified {
    fmt.Printf("Authenticated in %dµs\n", result.LatencyUs)
    fmt.Printf("Confidence: %.4f\n", result.Confidence)
} else {
    fmt.Println("Verification failed")
}

Understanding the Response

The verification response contains three layers of information: the match result, the latency breakdown, and the cryptographic attestation. Let's examine each.

Step 6: Independently Verify the Attestation

The attestation signature is not just metadata — it is a cryptographic proof that the verification result was produced by H33 infrastructure. You should verify this signature in your backend before trusting the result. This prevents man-in-the-middle tampering, replay attacks, and forged responses.

Attestation Verification with Node.js

import { verifyAttestation } from '@h33/sdk';

// The SDK provides a built-in verification helper
const isValid = await verifyAttestation({
  signature: result.attestation.signature,
  publicKey: result.attestation.publicKey,
  payloadHash: result.attestation.payloadHash,
  algorithm: 'dilithium3',
});

if (!isValid) {
  throw new Error('Attestation signature verification failed — reject this result');
}
// Signature is valid — the result was genuinely produced by H33

Attestation Verification with Python

from h33 import verify_attestation

is_valid = verify_attestation(
    signature=result.attestation.signature,
    public_key=result.attestation.public_key,
    payload_hash=result.attestation.payload_hash,
    algorithm="dilithium3",
)

if not is_valid:
    raise ValueError("Attestation verification failed")

Batch Authentication

For high-throughput scenarios — event check-in, workforce clock-in, financial transaction batches — H33 supports batch verification. A single API call can verify up to 32 users simultaneously with no per-user latency increase. The FHE scheme uses SIMD batching to pack 32 user templates into a single ciphertext operation.

curl -X POST https://api.h33.ai/v1/auth/verify/batch \
  -H "Authorization: Bearer $H33_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      { "user_id": "user_001", "biometric_vector": [...], "modality": "face" },
      { "user_id": "user_002", "biometric_vector": [...], "modality": "face" },
      { "user_id": "user_003", "biometric_vector": [...], "modality": "face" }
    ],
    "threshold": 0.85,
    "require_attestation": true
  }'

# Response: array of results, one per user, single attestation for the batch
{
  "results": [
    { "user_id": "user_001", "verified": true,  "confidence": 0.9812 },
    { "user_id": "user_002", "verified": true,  "confidence": 0.9634 },
    { "user_id": "user_003", "verified": false, "confidence": 0.6201 }
  ],
  "batch_latency_us": 1375,
  "per_auth_us": 46,
  "attestation": {
    "algorithm": "dilithium3",
    "signature": "base64...",
    "covers_batch": true
  }
}

Batch verification uses a single Dilithium attestation per batch rather than per user, reducing signature overhead by up to 31x. For a full analysis of batch performance, see Batch Auth: 8M/sec.

Webhooks: Real-Time Event Notifications

H33 can push authentication events to your server in real time via webhooks. This is useful for audit logging, anomaly detection, and triggering downstream workflows (e.g., granting access, updating session state, or alerting on failed verifications).

Register a webhook endpoint in your dashboard, then handle incoming events:

import express from 'express';
import { verifyWebhookSignature } from '@h33/sdk';

const app = express();
app.use(express.json());

app.post('/webhooks/h33', (req, res) => {
  // Verify the webhook signature (Dilithium-signed)
  const isValid = verifyWebhookSignature(
    req.body,
    req.headers['x-h33-signature'],
    process.env.H33_WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { event, data } = req.body;

  switch (event) {
    case 'auth.verified':
      console.log(`User ${data.user_id} authenticated (${data.latency_us}µs)`);
      break;
    case 'auth.failed':
      console.log(`Auth failed for ${data.user_id}: ${data.reason}`);
      break;
    case 'enrollment.created':
      console.log(`New enrollment: ${data.enrollment_id}`);
      break;
  }

  res.status(200).json({ received: true });
});

Error Handling

H33's API uses standard HTTP status codes. All error responses include a machine-readable error_code and a human-readable message. For a comprehensive treatment of error handling patterns, see our Error Handling Best Practices guide.

try {
  const result = await h33.auth.verify({ userId, biometricVector, modality: 'face' });
} catch (err) {
  if (err.statusCode === 404) {
    // User not enrolled — redirect to enrollment flow
    return redirectToEnrollment(userId);
  }
  if (err.statusCode === 429) {
    // Rate limited — retry after the Retry-After header
    const retryAfter = err.headers['retry-after'] || 1;
    await sleep(retryAfter * 1000);
    return retryVerification(userId, biometricVector);
  }
  // Unexpected error — log and alert
  logger.error('H33 verification error', { code: err.errorCode, msg: err.message });
  throw err;
}

Supported Biometric Modalities

H33 supports multiple biometric modalities through the same API. The modality parameter in enrollment and verification requests determines how the template is processed. For advanced setups, you can combine modalities using multimodal biometric fusion.

Production Deployment Checklist

Before going live, review this checklist to ensure your integration is secure, reliable, and performant.

Security

• API key in secrets manager — never in source code, environment files committed to git, or client-side bundles
• Verify attestation server-side — always check the Dilithium signature before trusting the result
• Validate webhook signatures — reject any webhook delivery that fails HMAC or Dilithium verification
• Use HTTPS exclusively — the SDK enforces TLS 1.3 by default; do not downgrade
• Set appropriate thresholds — a threshold of 0.85 balances security and usability for most face recognition; tune based on your FAR/FRR requirements
• Implement liveness detection — always perform liveness checks on the client side before submitting biometric vectors to H33

Reliability

• Enable retries — the SDK retries on 5xx errors by default (configurable; default is 2 retries with exponential backoff)
• Set request timeouts — 5 seconds is recommended for most deployments; H33 responses typically arrive in under 50ms including network
• Handle 429 gracefully — respect the Retry-After header; do not retry immediately
• Monitor with webhooks — set up webhook handlers for auth.failed events to detect anomalies
• Log attestation hashes — store payload_hash values for audit trails and dispute resolution

Performance

• Use batch verification — for any scenario processing more than one user at a time, batch calls reduce per-user cost from ~50µs to ~43µs
• Choose the nearest region — H33 is available in us-east-1, eu-west-1, and ap-southeast-1; network latency dominates server-side processing time
• Cache enrollment IDs — avoid redundant lookups by storing the enrollment_id with the user record in your database
• Profile your biometric pipeline — the biometric capture (camera, sensor, encoding model) is typically the slowest part of the flow; H33's server-side processing is ~50µs

What Happens Under the Hood

When you call /v1/auth/verify, H33 executes a three-stage pipeline that combines three fundamentally different cryptographic primitives. Each stage produces a verifiable output that feeds into the next. Here is the high-level flow:

Managing Enrollments

After the initial enrollment, you may need to list, update, or delete user templates. The enrollment management endpoints give you full lifecycle control.

List Enrollments

curl -s https://api.h33.ai/v1/auth/enrollments?limit=10 \
  -H "Authorization: Bearer $H33_API_KEY" | jq .

# Returns paginated list of enrolled users
{
  "enrollments": [
    {
      "enrollment_id": "enr_8xKm3Qf2vR7nL9pW",
      "user_id": "user_jane_doe_001",
      "modality": "face",
      "created_at": "2026-01-16T14:32:01Z",
      "last_verified": "2026-01-16T14:33:07Z"
    }
  ],
  "total": 1,
  "has_more": false
}

Re-Enroll (Update Template)

curl -X PUT https://api.h33.ai/v1/auth/enroll \
  -H "Authorization: Bearer $H33_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_jane_doe_001",
    "biometric_vector": [0.0241, -0.1878, 0.4532, ...],
    "modality": "face",
    "reason": "template_refresh"
  }'

# The old template is replaced; enrollment_id remains the same

Delete Enrollment

curl -X DELETE https://api.h33.ai/v1/auth/enroll \
  -H "Authorization: Bearer $H33_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "user_jane_doe_001" }'

# Template is permanently deleted; cannot be recovered
{
  "deleted": true,
  "user_id": "user_jane_doe_001",
  "deleted_at": "2026-01-16T15:00:00Z"
}

Testing Your Integration

H33 provides a sandbox environment for integration testing. Sandbox API keys (h33_test_ prefix) return deterministic, non-cryptographic responses so you can write reliable automated tests.

import { describe, it, expect } from 'vitest';
import { H33Client } from '@h33/sdk';

const h33 = new H33Client({
  apiKey: 'h33_test_pk_sandbox_key_here',  // sandbox key
});

describe('H33 Authentication', () => {
  it('enrolls a user successfully', async () => {
    const result = await h33.auth.enroll({
      userId: 'test_user_001',
      biometricVector: new Array(128).fill(0.1),
      modality: 'face',
    });
    expect(result.enrollmentId).toBeDefined();
    expect(result.templateEncrypted).toBe(true);
  });

  it('verifies a matching biometric', async () => {
    const result = await h33.auth.verify({
      userId: 'test_user_001',
      biometricVector: new Array(128).fill(0.1),  // positive first element → match
      modality: 'face',
    });
    expect(result.verified).toBe(true);
    expect(result.latencyUs).toBeGreaterThan(0);
  });

  it('rejects a non-matching biometric', async () => {
    const result = await h33.auth.verify({
      userId: 'test_user_001',
      biometricVector: new Array(128).fill(-0.1), // negative first element → no match
      modality: 'face',
    });
    expect(result.verified).toBe(false);
  });
});

For a comprehensive guide to testing authentication flows — including load testing, chaos engineering, and CI/CD integration — see Testing Authentication Flows.

Next Steps

You now have a working H33 integration. From here, you can expand into more advanced features and architectural patterns.

Language-Specific Tutorials

For deeper, language-specific walkthroughs that go beyond this quickstart:

• Node.js Authentication Tutorial — Express.js integration with middleware patterns
• Python Authentication Tutorial — FastAPI and Django integration
• Go Authentication Tutorial — net/http and gRPC integration
• Rust Authentication Tutorial — Actix-web and Axum integration

Summary

In this guide you completed the full H33 quickstart journey:

1. Created an API key — free tier with 1,000 authentications per month
2. Installed the SDK — available for Node.js, Python, Go, and Rust
3. Initialized the client — with region selection, timeout, and retry configuration
4. Enrolled a user — biometric template encrypted under FHE before transmission
5. Verified an authentication — ~50µs server-side, with FHE match + ZKP + post-quantum attestation
6. Verified the attestation — independently checked the Dilithium signature
7. Set up batch verification — up to 32 users per ciphertext for high-throughput scenarios
8. Configured webhooks — real-time event notifications with signature verification
9. Implemented error handling — graceful degradation with retry logic
10. Reviewed the production checklist — security, reliability, and performance best practices

H33 delivers sub-millisecond authentication with full post-quantum security, and the entire pipeline — FHE biometric matching, zero-knowledge verification, and Dilithium attestation — is exposed through a single API call. No cryptographic expertise is required on your end. The hardest part of post-quantum migration is starting — and you just did.