Key SDK
Integration Guide

Overview

The H33-Key SDK encrypts, decrypts, and verifies API keys and secrets in place — replacing plaintext credentials with post-quantum ciphertext wherever they live. A single npm install (or pip install, go get, cargo add) gives you access to the full H33-Key pipeline: Kyber-1024 envelope encryption, AES-256-GCM symmetric encryption, HMAC-SHA3 integrity verification, and Dilithium digital signatures for cryptographic provenance.

For companies integrating Key-FHE into their platform (e.g., verifying incoming API keys without seeing them), the server-side SDK provides FHE-based key comparison — the same BFV homomorphic encryption engine that powers H33 Biometrics, applied to key verification.

Quick Start

Install the SDK and encrypt your first key in under 60 seconds.

npm install @h33/key-sdk

import { H33Key } from '@h33/key-sdk';

const h33 = new H33Key({ apiKey: 'h33_key_...' });

// Encrypt a key in place
const { ciphertext, keyId } = await h33.encrypt({
  keyMaterial: process.env.STRIPE_SECRET_KEY,
  tier: 'key-0',  // or key-1, key-2, key-3
  ttl: 300        // auto-zero after 5 minutes
});

// Store ciphertext wherever the plaintext used to live
process.env.STRIPE_SECRET_KEY = ciphertext;

// Decrypt at point of use
const plaintext = await h33.decrypt({ keyId });

Server-Side Integration

This section is for companies integrating Key-FHE into their platform — services that accept API keys from customers and need to verify them without seeing plaintext. Think GitLab verifying deploy tokens, AWS verifying access keys, or payment processors verifying merchant credentials.

import { H33KeyServer } from '@h33/key-sdk/server';

const server = new H33KeyServer({ apiKey: 'h33_key_...' });

// Register accepted keys (FHE enrollment)
const { enrollmentId } = await server.fhe.register({
  keyId: 'hk_abc123',
  purpose: 'api_authentication'
});

// Verify incoming encrypted key via FHE
const { match, confidence } = await server.fhe.verify({
  enrollmentId,
  encryptedKey: incomingCiphertext,
  challenge: await server.fhe.getChallenge()
});

// Handle revocation callbacks
server.onRevocation((event) => {
  console.log(`Key ${event.keyId} revoked: ${event.reason}`);
  // Invalidate sessions using this key
});

Gateway Configuration

The H33-Gateway is a TEE-based proxy that makes API calls on your behalf. Instead of decrypting a key and calling Stripe directly, your app sends the request to H33-Gateway — which decrypts the key inside an AWS Nitro Enclave, calls Stripe, and returns the response. Your infrastructure never sees the plaintext key.

// Configure a proxy target
await h33.gateway.configure({
  targetId: 'stripe-api',
  baseUrl: 'https://api.stripe.com',
  authHeader: 'Authorization',
  authTemplate: 'Bearer {{key}}',
  allowedPaths: ['/v1/charges', '/v1/customers', '/v1/payment_intents']
});

// Make a proxied API call — your infra never sees the plaintext key
const response = await h33.gateway.proxy({
  targetId: 'stripe-api',
  keyId: 'hk_abc123',
  method: 'POST',
  path: '/v1/charges',
  body: { amount: 2000, currency: 'usd' }
});

Gateway Flow

Language SDKs

H33-Key ships SDKs for four languages. All SDKs share the same API surface and connect to the same backend.

import { H33Key } from '@h33/key-sdk';

const h33 = new H33Key({ apiKey: 'h33_key_...' });
const result = await h33.encrypt({
  keyMaterial: process.env.STRIPE_SECRET_KEY,
  tier: 'key-0'
});

from h33_key import H33Key
import os

h33 = H33Key(api_key="h33_key_...")
result = h33.encrypt(
    key_material=os.environ["DB_PASSWORD"],
    tier="key-1"
)

client := h33key.New("h33_key_...")
result, _ := client.Encrypt(ctx, h33key.EncryptInput{
    KeyMaterial: os.Getenv("DB_PASSWORD"),
    Tier: "key-1",
})

let client = H33Key::new("h33_key_...")?;
let result = client.encrypt(EncryptInput {
    key_material: std::env::var("DB_PASSWORD")?,
    tier: Tier::Key1,
    ttl: Some(300),
}).await?;

Docker Sidecar

For environments you cannot modify (legacy apps, third-party containers), deploy the H33-Key sidecar as a companion container. It intercepts environment variables, decrypts them at startup, and makes plaintext available via a Unix socket — your app code stays unchanged.

# docker-compose.yml
services:
  h33-key-sidecar:
    image: h33ai/key-sidecar:latest
    environment:
      H33_API_KEY: h33_key_...
      H33_KEY_TIER: key-1
      H33_DECRYPT_ENV: STRIPE_KEY,DB_PASSWORD,SSH_KEY
    volumes:
      - /var/run/h33:/var/run/h33

  your-app:
    image: your-app:latest
    volumes:
      - /var/run/h33:/var/run/h33
    environment:
      # These will be auto-decrypted by the sidecar
      STRIPE_KEY: "${ENCRYPTED_STRIPE_KEY}"
      DB_PASSWORD: "${ENCRYPTED_DB_PASSWORD}"

CI/CD Integration

Decrypt keys at deploy time without storing plaintext in your CI/CD platform. H33 provides native integrations for GitHub Actions, GitLab CI, and Jenkins.

GitHub Actions

- name: Decrypt deploy keys
  uses: h33-ai/key-decrypt-action@v1
  with:
    api-key: ${{ secrets.H33_API_KEY }}
    keys: |
      DEPLOY_KEY=hk_abc123
      DB_PASSWORD=hk_def456

GitLab CI

decrypt_keys:
  image: h33ai/key-cli:latest
  script:
    - h33-key decrypt --key-id $DEPLOY_KEY_ID --output DEPLOY_KEY
    - h33-key decrypt --key-id $DB_PASS_ID --output DB_PASSWORD

Jenkins

pipeline {
  environment {
    DEPLOY_KEY = h33KeyDecrypt(keyId: 'hk_abc123')
  }
}

Revocation & Rotation

Every encrypted key gets a unique ID (hk_*) that serves as the handle for lifecycle management. Revoke compromised keys instantly, rotate to new material with grace periods, and monitor status via webhooks.

• Revoke: Mark a key ID as revoked — all future decrypt() and verify() calls return REVOKED.
• Rotate: Generate a new Kyber envelope and key ID. The old ID gets a configurable grace period, then auto-revokes.
• Status: GET /v1/key/status/:id returns active, rotated, or revoked.
• Webhooks: Real-time notifications for revocation, rotation, and expiry events.

// Revoke a compromised key
await h33.revoke({
  keyId: 'hk_compromised123',
  reason: 'potential_exposure'
});

// Rotate to new key material
const { newKeyId, oldKeyId, gracePeriod } = await h33.rotate({
  keyId: 'hk_abc123',
  newKeyMaterial: generateNewApiKey(),
  gracePeriodSeconds: 3600  // 1 hour overlap
});

Security Model

H33-Key is built on NIST-standardized post-quantum cryptography. Every layer is designed to resist both classical and quantum attacks.

API Reference

Complete reference for all H33-Key API endpoints. All endpoints require an Authorization: Bearer h33_key_... header.

Key Operations

Gateway

FHE Verification

Lifecycle