EcoQuota API Reference

1. # Create a workspace (or do this in the Dashboard UI)
POST https://ecoquota.kodenesiadigital.workers.dev/api/auth/signup
{ "name": "Acme", "email": "team@acme.dev", "password": "s3cure-pass" }

2. # Create an API key for one of your customers
POST https://ecoquota.kodenesiadigital.workers.dev/api/v1/keys
Authorization: Bearer <your-session-token>
{ "user_email": "customer@client.com", "quota_limit": 5000 }

3. # In your backend, verify before serving the request
GET https://ecoquota.kodenesiadigital.workers.dev/v1/verify
Authorization: Bearer eq_live_xxxxxxxxxxxxxxxx

POST /api/auth/signup
{ "name": "Acme", "email": "team@acme.dev", "password": "s3cure-pass" }

# 201 Created
{
  "workspace": { "id": "…", "name": "Acme", "email": "team@acme.dev", "tier": "free", "active": 1 },
  "token": "ey…",                 // session token — store it
  "expires_at": "…"
}

POST /api/auth/login
{ "email": "team@acme.dev", "password": "s3cure-pass" }

# 200 OK — same shape as signup
{ "workspace": { … }, "token": "ey…", "expires_at": "…" }

{
  "ok": true,
  "key_id": "…",
  "key_prefix": "eq_live_abcd",
  "quota": {
    "period": "2026-09",         // YYYY-MM (monthly) or YYYY-MM-DD (daily), UTC
    "period_type": "monthly",
    "used": 321,
    "limit": 5000,
    "percent": 6,
    "remaining": 4679
  }
}

// 429 Too Many Requests
{
  "ok": false,
  "error": "quota_exceeded",
  "quota": { "period": "2026-09", "period_type": "monthly", "used": 5001, "limit": 5000, "percent": 100, "remaining": 0 }
}

POST /api/v1/keys
Authorization: Bearer <session-token>
{ "user_email": "customer@client.com", "quota_limit": 1000, "quota_period": "monthly" }

# 201 Created
{
  "id": "…", "user_id": "…", "name": "default",
  "key": "eq_live_1f3c9d2a…",      // shown ONLY here
  "key_prefix": "eq_live_1f3c",
  "status": "active",
  "quota_period": "monthly",
  "quota_limit": 1000,
  "note": "Save this key now — it is shown only once."
}

POST /api/v1/users
Authorization: Bearer <session-token>
{ "name": "DataCorp", "email": "ops@datacorp.io", "webhook_url": "https://api.datacorp.io/ecoquota/hook" }

# 201 Created — the secret is returned only here (used to verify webhook signatures)
{ "user": { … }, "webhook_secret": "2f6a…" }

POST <your webhook_url>
Content-Type: application/json
User-Agent: EcoQuota/1.0
X-EcoQuota-Event: quota_80
X-EcoQuota-Signature: sha256=<lowercase-hex-hmac>

{
  "event": "quota_80",
  "key_id": "…",
  "key_prefix": "eq_live_1f3c",
  "key_name": "default",
  "user": { "id": "…", "name": "DataCorp", "email": "ops@datacorp.io" },
  "quota": { "period": "2026-09", "period_type": "monthly", "used": 4000, "limit": 5000, "percent": 80, "remaining": 1000 },
  "timestamp": "2026-09-05T12:00:00.000Z"
}

signature = sha256 = HEX( HMAC-SHA256( secret, rawBody ) )   // lowercase hex

// Node.js — validate before trusting the payload
const crypto = require("crypto");

function verify(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");
  const provided = signatureHeader.replace(/^sha256=/, "");
  const a = Buffer.from(expected), b = Buffer.from(provided);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// const ok = verify(req.rawBody, req.headers["x-ecoquota-signature"], userSecret);

curl -s -o /dev/null -w "%{http_code}\n" \
  https://ecoquota.kodenesiadigital.workers.dev/v1/verify \
  -H "Authorization: Bearer eq_live_xxxxxxxx"
# → 200, 401, or 429

async function checkKey(key) {
  const res = await fetch("https://ecoquota.kodenesiadigital.workers.dev/v1/verify", {
    headers: { "Authorization": `Bearer ${key}` },
  });
  const body = await res.json();
  if (res.status === 200) {
    return { allow: true, quota: body.quota };
  }
  return { allow: false, reason: body.error || body.message, quota: body.quota };
}

import requests

def check_key(api_key):
    r = requests.get(
        "https://ecoquota.kodenesiadigital.workers.dev/v1/verify",
        headers={"Authorization": f"Bearer {api_key}"},
    )
    body = r.json()
    return r.ok, body.get("quota"), body.get("error")

import (
  "encoding/json"
  "net/http"
)

func verifyKey(key string) (int, string) {
  req, _ := http.NewRequest(http.MethodGet, "https://ecoquota.kodenesiadigital.workers.dev/v1/verify", nil)
  req.Header.Set("Authorization", "Bearer "+key)
  res, err := http.DefaultClient.Do(req)
  if err != nil { return 500, "" }
  defer res.Body.Close()
  var body struct { Error string `json:"error"` }
  json.NewDecoder(res.Body).Decode(&body)
  return res.StatusCode, body.Error
}

const { url } = await fetch("https://ecoquota.kodenesiadigital.workers.dev/api/billing/polar/checkout").then(r => r.json());
window.location.href = url; // → https://buy.polar.sh/…