Skip to main content

Zeq BYOK

Register an upstream API and its auth header (your OpenAI / Anthropic / any-provider key). The header is encrypted at rest with AES-256-GCM and is never returned to anyone — the platform forwards through it without ever exposing the plaintext.

  • Live app → /apps/zeq-byok/
  • Source → shared/api-core/src/routes/apisRoutes.ts + shared/api-core/src/lib/encryptedRow.ts
  • Construction → AES-256-GCM field encryption (encryptField), fresh IV per write, owner-authenticated
  • Storage → user_external_apis — auth_header_enc / auth_header_iv columns; plaintext never persisted

What it actually does​

BYOK lets you register an upstream API plus the auth header it needs (typically a provider API key), so Zeq apps can call that API on your behalf without your key ever being stored in the clear. The construction is straightforward at-rest field encryption — no KMS wrapping, no expiry windows:

  1. Register — POST /api/zeq/apis/:slug (owner-authenticated) takes { name, base_url, auth_header, ... }. The auth_header is immediately encrypted with encryptField — AES-256-GCM with a fresh IV — and only the ciphertext + IV (auth_header_enc, auth_header_iv) are written to the database. The plaintext is discarded.
  2. List — GET /api/zeq/apis/:slug returns your registered APIs but never the auth header: callers get a has_auth_header flag and a masked hint, nothing more.
  3. Forward — when an app calls through your registered API, the server decrypts the header in memory just long enough to attach it to the outbound request. It is never returned in any response body.

The confidentiality boundary is AES-256-GCM under the framework master key (ZEQ_FIELD_KEY). The same encryptField primitive protects every BYOK header and is the same AES-256-GCM-at-rest mechanism the Vault uses.

The construction, step by step​

StageMechanismStandard
At-rest encryptionAES-256-GCM via encryptField, fresh IV per writeNIST SP 800-38D
Storageauth_header_enc + auth_header_iv; plaintext discarded—
Read protectionheader never returned — only has_auth_header flag + masked hint—
Authorizationowner-authenticated (Bearer machine API key); 4 KB header cap—

Runnable worked example — register an external API with your own key​

BYOK is exposed under /api/zeq/apis/:slug (owner-authenticated). You register an upstream API plus its auth header; the header is encrypted at rest (the framework's ZSC vault, AES-256-GCM) — the plaintext key never touches the DB unencrypted.

# 1. Register an upstream API for your machine, with your key in the auth header
curl -s -X POST https://zeqsdk.com/api/zeq/apis/$SLUG \
  -H "Authorization: Bearer $ZEQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "openai",
    "base_url": "https://api.openai.com",
    "auth_header": "Authorization: Bearer sk-…your-own-key…",
    "rate_limit_per_min": 60
  }'

# 2. List what's registered (auth headers come back redacted, never in plaintext)
curl -s https://zeqsdk.com/api/zeq/apis/$SLUG \
  -H "Authorization: Bearer $ZEQ_API_KEY"

# 3. Server-side test forward through the stored credential
curl -s -X POST https://zeqsdk.com/api/zeq/apis/$SLUG/$API_ID/test \
  -H "Authorization: Bearer $ZEQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "path": "/v1/models", "method": "GET" }'

The stored auth header is encrypted with the framework's field key (AES-256-GCM); registrations are owner-authenticated. Your key stays yours — the platform forwards through it without ever returning the plaintext.

Extend it​

  • Rate-limited forwarding: each registered API carries a rate_limit_per_min, enforced server-side so a stored key can't be abused.
  • Server-side test: POST /api/zeq/apis/:slug/:id/test round-trips through the stored credential without the caller ever handling the plaintext key.
  • Multiple providers: register OpenAI, Anthropic, and others side by side; each header is independently encrypted with its own IV.

Seeds​

  • Master-key rotation: BYOK headers re-encrypt under a rotated ZEQ_FIELD_KEY exactly like every other field — old key in ZEQ_FIELD_KEY_PREV, new key live.
  • Post-quantum at rest: AES-256-GCM remains a sound choice against quantum adversaries for confidentiality; no envelope-wrapping change needed.
  • Per-tenant separation: domain-separate the field KDF salt per tenant so one tenant's stored keys are cryptographically distinct from another's.

Papers​

Middleware active. Kernel on the 1.287 Hz HulyaPulse. Awaiting next Zeqond.