Keywave

ImportantThese docs are for developers with valid API keys. Requests without a key (or with an invalid key) will fail. Never expose your API key in client-side code.

Integrate Keywave in 3 Calls.

Production flow: Get phrase → Enroll (once) → Verify (with phrase). Voice templates are protected; raw audio is never stored in Keywave.

PilotNew accounts that add a card at signup receive 1,000 free proofs to start testing immediately. Pilots run on the same production-grade API and infrastructure from day one (no separate demo environment).

Credits apply to verification usage. When credits are exhausted, usage continues on your plan.

PlaygroundThe Playground is a developer page where you can run the Keywave flow end to end from your browser. It is designed to help you validate your API key, see real responses, and confirm your integration logic before wiring Keywave into your product.

The Playground uses the same API you will call from your server. It is intended for developer testing, not for end user traffic.

NotePlayground requests burn proofs the same way production requests do. There are no special caps or separate pools.

Keep your API key private. Use the Playground only in trusted developer contexts.

Open Playground

NewNeed end-user stamping UX? See the copy-paste guide: Verify + Stamp Integration

BillingUsage is billed per verification. See Pricing.

EVMOptional EVM mirroring via Ethereum Attestation Service (EAS) is available for Production & Scale. Learn more: EVM Mirroring.

Base URL & Environments

All requests are made to https://api.keywave.io. Use environment variables on your server to switch between staging/production as needed (never embed keys in client apps).

Pilots use the same production endpoints and reliability guarantees from day one.

API Keys & Auth

Send your key via x-api-key. Keys must stay server-side.

Required headers

  • x-api-key: <YOUR_API_KEY>
  • Content-Type: application/json

Rate limitsLimits are enforced per API key and defended by per-IP protections. 429 responses include a retry hint:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1733572800

Need higher limits or SLAs? support@keywave.io.

Supported Audio Formats & Constraints

  • Formats: m4a, mp3, wav, webm.
  • Channels: mono preferred; stereo accepted.
  • Sample rate: 16–48 kHz.
  • Length: 1–5 seconds recommended; max 15 seconds.
  • URLs may be public or signed (HTTPS required).

Privacy & Data Handling

  • No raw audio is stored by Keywave.
  • Templates are privacy-preserving and salted; not reversible to audio.
  • Phrase challenges are single-use and short-lived.
  • On-chain stamps are minimal receipts (no personal data).

Quickstart

1) Get a one-time phrase, 2) Enroll a voice template (once), 3) Verify with phrase.

1) POST /api/v1/phrase

Returns phrase_id, prompt, and expires_at. Single-use; expires quickly.

curl -s https://api.keywave.io/api/v1/phrase \
  -H "Content-Type: application/json" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -d '{"wallet":"<WALLET_ID>"}' | jq

2) POST /api/v1/enroll

Create/update a protected voice template from a public or signed URL.

curl -s https://api.keywave.io/api/v1/enroll \
  -H "Content-Type: application/json" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -d '{
    "wallet":"<WALLET_ID>",
    "audioUrl":"https://<your-signed-or-public>/voice/enroll.m4a",
    "projection_id":"p0",
    "params_version":"v1"
  }' | jq

3) POST /api/v1/verify (phrase required)

Submit a fresh recording of the prompted phrase. Response includes gate signals and optional stamp.

curl -s https://api.keywave.io/api/v1/verify \
  -H "Content-Type: application/json" \
  -H "x-api-key: <YOUR_API_KEY>" \
  -d '{
    "wallet":"<WALLET_ID>",
    "audioUrl":"https://<your-signed-or-public>/voice/verify.m4a",
    "projection_id":"p0",
    "params_version":"v1",
    "phrase_id":"pc_xxx"
  }' | jq

For a complete UI flow (show “Verified / Stamp now”), see Verify + Stamp Integration.

Idempotency & Retries

If you retry due to network errors, reuse the same phrase_id until it succeeds or expires. Do not recycle a used phrase; request a new one.

Legacy Hash Flow (Deprecated)

Historical hash-only endpoints remain for backward compatibility but are not recommended.

# Enroll legacy hash
curl -s https://api.keywave.io/api/v1/enroll -H "Content-Type: application/json" -H "x-api-key: <YOUR_API_KEY>" \
  -d '{"wallet":"<WALLET_ID>","phrase_hash":"<SHA256_HEX>"}' | jq

# Verify legacy hash
curl -s https://api.keywave.io/api/v1/verify -H "Content-Type: application/json" -H "x-api-key: <YOUR_API_KEY>" \
  -d '{"wallet":"<WALLET_ID>","probe_hash":"<SHA256_HEX>"}' | jq

HTTP Status by Endpoint

/v1/phrase

  • 200 — issued { phrase_id, prompt, expires_at }
  • 401 — invalid/missing API key
  • 429 — rate limited (see Retry-After)
  • 500 — server/db error

/v1/enroll

  • 200 — created/updated
  • 400 — missing wallet or invalid audioUrl
  • 401 — invalid/missing API key
  • 429 — rate limited
  • 500 — server/db error

/v1/verify

  • 200 — result payload (includes gates + stamp)
  • 400 — MISSING_PHRASE | PHRASE_EXPIRED | PHRASE_ALREADY_USED
  • 401 — invalid/missing API key
  • 404 — no voice template
  • 429 — rate limited
  • 502 — upstream ASR/verify error
  • 500 — server/db error

Monitoring & Abuse Protection

  • Per-key quotas with per-IP shields; logs stored in verify_logs.
  • Alerts on elevated 5xx, p95 latency, or unusual request bursts.
  • Keys can be rotated at any time from your console. If leaked, revoke immediately.

References

Powered by Keywave