Kovio / APIDEVELOPER GUIDE

PRE-LAUNCH DOCUMENTATION

Build a useful scan.

QR images and structured payloads over HTTPS. Choose the authentication method for where your code runs.

Choose your path

Access is limited to two approved Google identities. The account gate is not a public developer launch. Open the dashboard once to initialize your approved account.

Server quickstart

Create a key in the dashboard, copy it once into a server secret or environment variable, then dismiss it. Never paste the key into HTML, an APK, chat, a URL, screenshots or source control.

In the commands below, set KOVIO_API_KEY privately in your server environment. The example contains no working credential.

curl https://kovio-developers.n97485211.workers.dev/v1/qr \
  -H "Authorization: Bearer $KOVIO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"text":"Hello from Kovio","format":"png","size":320}' \
  --output qr.png

Node.js18+ server example:

const r = await fetch(
  'https://kovio-developers.n97485211.workers.dev/v1/qr', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.KOVIO_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({text:'Hello from Kovio', format:'png', size:320})
  });
if (!r.ok) throw new Error(`Kovio ${r.status}: ${await r.text()}`);
await (await import('node:fs/promises')).writeFile(
  'qr.png', new Uint8Array(await r.arrayBuffer())
);

Use the same pattern from Python, Java, Go or any HTTPS-capable server. Those language integrations have not each been independently tested. Do not blindly retry a POST after an uncertain network failure: a completed request may already have consumed quota. Idempotency keys are not implemented.

HTML and browser integration

The hosted quickstart demonstrates a real browser request. It uses Firebase Google sign-in, obtains the current user's short-lived identity token, and calls the client endpoint. The token authenticates the person, not a permanent shared application secret.

// After Firebase Google sign-in in the configured project:
const idToken = await auth.currentUser.getIdToken();
const r = await fetch('/client/v1/qr', {
  method:'POST',
  headers:{Authorization:`Bearer ${idToken}`, 'Content-Type':'application/json'},
  body:JSON.stringify({text:'Hello from my page', format:'png', size:320})
});
if (!r.ok) throw new Error(`Kovio ${r.status}`);
const image = await r.blob();

The snippet assumes Firebase has already been initialized and Google sign-in completed; it is not a complete standalone login implementation. The hosted page loads its SDK bundle and stylesheet from this same site. Downloading only its HTML does not turn it into an offline app.

For your own host, provide the exact HTTPS origin (scheme, host and port) for approval and configure the sign-in domain. Local development needs an explicitly approved localhost origin. A downloaded file:// page has an opaque/null origin and is not enabled. Do not work around this with mode:'no-cors' or by embedding a server key.

Only the client image/payload routes are intended for client CORS. Dashboard key-management endpoints remain restricted to the dashboard origin. Tokens stay in the authentication session; never log, share or put them in request URLs. A stolen token can still be abused during its lifetime. Short-lived does not mean public.

Android and other native clients

Use the platform's supported Google/Firebase sign-in flow, then obtain a fresh Firebase ID token and send it through HTTPS Bearer authentication to /client/v1/qr or /client/v1/payload. Do not ship a permanent kv_live_ key in the app package. CORS is a browser rule, not protection against native clients.

Before claiming Android readiness we need the app's package identity, signing certificate registration and a physical-device test. This release does not register a new app, ship an Android SDK, or prove native sign-in works. The same distinction applies to iOS. System/browser-based authorization is preferable to collecting Google credentials inside a custom WebView.

Endpoint reference

Image: POST /v1/qr for server keys; POST /client/v1/qr for verified user tokens. JSON in; image/png or image/svg+xml out.

{"payload":{"type":"url","url":"https://example.com"},
 "format":"svg","size":512,"errorCorrection":"M"}

Encoded text only: POST /v1/payload or POST /client/v1/payload. Returns JSON, not an image:

Request:  {"type":"url","url":"https://example.com"}
Response: {"text":"https://example.com/"}

Payload builders include text, URL, Wi-Fi, email, phone, SMS, vCard, geo and UPI. UPI only encodes supplied data; it does not verify the payee or any payment. Use the image endpoint with payload when you want a QR image in one call.

Requests must use Content-Type: application/json. Body limit4096bytes. Unknown fields and URL query strings are rejected. Images are generated per request; this API does not host a persistent QR image URL or store an editable destination.

Errors and free limits

Errors are JSON: {"error":"machine_readable_code"}. Read HTTP status and the error code together. Do not send raw credentials or personal payloads when asking for help.

Accepted generation calls share100/account/day and10/minute across server keys and client identities;5,000/day globally. Daily counters reset at00:00 UTC. Extra attempt guards can reject requests sooner. Two active server keys/account,30-day expiry, at most5 key creations/day. Signups remain closed except the two approved accounts. No payment, paid fallback, uptime promise or automatic upgrade.

Successful image/payload responses include X-RateLimit-Remaining for the account's remaining daily quota. Per-request IDs, full SDKs, webhook delivery and idempotent retry storage are not implemented. They should not be inferred from other providers' docs.

Security and privacy checklist

References: OpenAI API overview, Firebase ID tokens, Native app authorization, CORS/null origins.