Kulawise API reference

curl https://api.kulawise.com/api/v1/access/me \
  -H "Authorization: Bearer kwb_live_YOUR_KEY"

# or
curl https://api.kulawise.com/api/v1/access/me \
  -H "X-Kulawise-Key: kwb_live_YOUR_KEY"

const res = await fetch("https://api.kulawise.com/api/v1/access/me", {
  headers: { Authorization: `Bearer ${process.env.KULAWISE_KEY}` },
});
const { data } = await res.json();
console.log(data.business_id);

import os, requests

res = requests.get(
    "https://api.kulawise.com/api/v1/access/me",
    headers={"Authorization": f"Bearer {os.environ['KULAWISE_KEY']}"},
    timeout=10,
)
print(res.json()["data"]["business_id"])

curl https://api.kulawise.com/api/v1/access/me \
  -H "Authorization: Bearer kwb_live_YOUR_KEY"

# or
curl https://api.kulawise.com/api/v1/access/me \
  -H "X-Kulawise-Key: kwb_live_YOUR_KEY"

const res = await fetch("https://api.kulawise.com/api/v1/access/me", {
  headers: { Authorization: `Bearer ${process.env.KULAWISE_KEY}` },
});
const { data } = await res.json();
console.log(data.business_id);

import os, requests

res = requests.get(
    "https://api.kulawise.com/api/v1/access/me",
    headers={"Authorization": f"Bearer {os.environ['KULAWISE_KEY']}"},
    timeout=10,
)
print(res.json()["data"]["business_id"])

curl -X POST https://api.kulawise.com/api/v1/access/check \
  -H "Authorization: Bearer kwb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"credential": "kulawise:pass:Q7K2M9:48213907"}'

const res = await fetch("https://api.kulawise.com/api/v1/access/check", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KULAWISE_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ credential: scanned }), // QR text or card number
});
const { data } = await res.json();
if (data.allowed) openRelay();
showOnScreen(data.message);

res = requests.post(
    "https://api.kulawise.com/api/v1/access/check",
    headers={"Authorization": f"Bearer {KEY}"},
    json={"credential": scanned},  # QR text or card number
    timeout=5,
)
data = res.json()["data"]
if data["allowed"]:
    open_relay()
show_on_screen(data["message"])

curl https://api.kulawise.com/api/v1/access/members \
  -H "Authorization: Bearer kwb_live_YOUR_KEY"

const res = await fetch("https://api.kulawise.com/api/v1/access/members", {
  headers: { Authorization: `Bearer ${process.env.KULAWISE_KEY}` },
});
const { data: members } = await res.json();

members = requests.get(
    "https://api.kulawise.com/api/v1/access/members",
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=10,
).json()["data"]

curl -X POST https://api.kulawise.com/api/v1/access/cards \
  -H "Authorization: Bearer kwb_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"card_uid": "04:a2:b3:c4:d5:e6:f7", "label": "Blue fob", "email": "ada@example.com"}'

const res = await fetch("https://api.kulawise.com/api/v1/access/cards", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KULAWISE_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    card_uid: "04:a2:b3:c4:d5:e6:f7",
    label: "Blue fob",
    email: "ada@example.com",
  }),
});
if (res.status === 409) console.log("That card is already given to someone");

res = requests.post(
    "https://api.kulawise.com/api/v1/access/cards",
    headers={"Authorization": f"Bearer {KEY}"},
    json={"card_uid": "04:a2:b3:c4:d5:e6:f7", "label": "Blue fob", "email": "ada@example.com"},
    timeout=10,
)
card = res.json()["data"]

curl -X DELETE https://api.kulawise.com/api/v1/access/cards/04A2B3C4D5E6F7 \
  -H "Authorization: Bearer kwb_live_YOUR_KEY"

const res = await fetch("https://api.kulawise.com/api/v1/access/cards/04A2B3C4D5E6F7", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.KULAWISE_KEY}` },
});
// 204 No Content on success, 404 if no active card has that number

res = requests.delete(
    "https://api.kulawise.com/api/v1/access/cards/04A2B3C4D5E6F7",
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=10,
)
assert res.status_code == 204

const BASE = "https://api.kulawise.com/api/v1";
const KEY = process.env.KULAWISE_KEY;
let cache = new Map(); // card UID -> member, for when the network drops

async function refreshCache() {
  try {
    const res = await fetch(`${BASE}/access/members`, {
      headers: { Authorization: `Bearer ${KEY}` },
    });
    if (!res.ok) return; // keep the last good list
    const { data } = await res.json();
    const next = new Map();
    for (const m of data) for (const uid of m.card_uids) next.set(uid, m);
    cache = next;
  } catch { /* offline: keep the last good list */ }
}
refreshCache();
setInterval(refreshCache, 5 * 60 * 1000);

// Call this with whatever the reader saw: QR text or card number.
async function onScan(credential) {
  try {
    const res = await fetch(`${BASE}/access/check`, {
      method: "POST",
      headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },
      body: JSON.stringify({ credential }),
      signal: AbortSignal.timeout(3000),
    });
    if (res.ok) {
      const { data } = await res.json();
      if (data.allowed) openRelay();
      return showOnScreen(data.message);
    }
    if (res.status < 500 && res.status !== 429) {
      const { error } = await res.json();
      return showOnScreen(error);
    }
  } catch { /* network down or timed out: fall through */ }

  // Offline fallback: only access cards can be matched locally.
  const uid = credential.replace(/[:\-\s]/g, "").toUpperCase();
  const m = cache.get(uid);
  if (m && new Date(m.ends_at) > new Date()) {
    openRelay();
    return showOnScreen("Welcome in.");
  }
  showOnScreen("Can't check right now. Please see the front desk.");
}

import os, re, time, threading
from datetime import datetime, timezone
import requests

BASE = "https://api.kulawise.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['KULAWISE_KEY']}"}
cache = {}  # card UID -> member, for when the network drops

def refresh_cache():
    global cache
    while True:
        try:
            res = requests.get(f"{BASE}/access/members", headers=HEADERS, timeout=10)
            if res.ok:
                cache = {uid: m for m in res.json()["data"] for uid in m["card_uids"]}
        except requests.RequestException:
            pass  # offline: keep the last good list
        time.sleep(300)

threading.Thread(target=refresh_cache, daemon=True).start()

def on_scan(credential: str):
    try:
        res = requests.post(f"{BASE}/access/check", headers=HEADERS,
                            json={"credential": credential}, timeout=3)
        if res.ok:
            data = res.json()["data"]
            if data["allowed"]:
                open_relay()
            return show_on_screen(data["message"])
        if res.status_code < 500 and res.status_code != 429:
            return show_on_screen(res.json()["error"])
    except requests.RequestException:
        pass  # network down or timed out: fall through

    # Offline fallback: only access cards can be matched locally.
    uid = re.sub(r"[:\-\s]", "", credential).upper()
    m = cache.get(uid)
    if m and datetime.fromisoformat(m["ends_at"].replace("Z", "+00:00")) > datetime.now(timezone.utc):
        open_relay()
        return show_on_screen("Welcome in.")
    show_on_screen("Can't check right now. Please see the front desk.")

import crypto from "node:crypto";

// rawBody must be the exact bytes received, before any JSON parsing.
export function verifyKulawise(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.`)
    .update(rawBody)
    .digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(parts.v1 ?? "", "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express: app.post("/hooks/kulawise", express.raw({ type: "application/json" }), (req, res) => {
//   if (!verifyKulawise(req.body, req.get("X-Kulawise-Signature"), process.env.KULAWISE_WHSEC))
//     return res.sendStatus(400);
//   const event = JSON.parse(req.body);
//   res.sendStatus(200);
// });

import hmac, hashlib, time

def verify_kulawise(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = parts.get("t", "")
    if not t.isdigit() or abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

# Flask:
# @app.post("/hooks/kulawise")
# def hook():
#     if not verify_kulawise(request.get_data(), request.headers["X-Kulawise-Signature"], WHSEC):
#         abort(400)
#     event = request.get_json()
#     return "", 200

# Query by username:
curl -X GET "https://api.kulawise.com/api/v1/partners/health-metrics?username=alex" \
  -H "X-Partner-Key: kula_YOUR_SECRET_KEY"

# Or query by email:
curl -X GET "https://api.kulawise.com/api/v1/partners/health-metrics?email=user@example.com" \
  -H "X-Partner-Key: kula_YOUR_SECRET_KEY"

async function getKulawiseMetrics({ email, username, date }) {
  const params = new URLSearchParams();
  if (username) params.append("username", username);
  else if (email) params.append("email", email);
  if (date) params.append("date", date);

  const response = await fetch(
    `https://api.kulawise.com/api/v1/partners/health-metrics?${params.toString()}`,
    {
      headers: {
        "X-Partner-Key": process.env.KULAWISE_API_KEY,
      },
    }
  );

  if (!response.ok) {
    if (response.status === 404) return null; // User not found
    throw new Error(`Kulawise API error: ${response.statusText}`);
  }

  const data = await response.json();
  return data.metrics;
}

import os
import requests

def get_kulawise_metrics(username: str = None, email: str = None):
    api_key = os.getenv("KULAWISE_API_KEY")
    url = "https://api.kulawise.com/api/v1/partners/health-metrics"

    headers = {
        "X-Partner-Key": api_key
    }
    params = {}
    if username:
        params["username"] = username
    elif email:
        params["email"] = email

    response = requests.get(url, headers=headers, params=params)

    if response.status_code == 404:
        return None  # User not found
    response.raise_for_status()

    return response.json()["metrics"]

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"
	"os"
)

type MetricsResponse struct {
	Email    string         `json:"email"`
	Username *string        `json:"username,omitempty"`
	UserName string         `json:"user_name"`
	Date     string         `json:"date"`
	Metrics  map[string]any `json:"metrics"`
	SyncedAt string         `json:"synced_at"`
}

func GetKulawiseMetrics(identifier, queryType string) (*MetricsResponse, error) {
	qParam := "username"
	if queryType == "email" {
		qParam = "email"
	}
	reqURL := fmt.Sprintf("https://api.kulawise.com/api/v1/partners/health-metrics?%s=%s", qParam, url.QueryEscape(identifier))
	req, err := http.NewRequest("GET", reqURL, nil)
	if err != nil {
		return nil, err
	}

	req.Header.Set("X-Partner-Key", os.Getenv("KULAWISE_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	if resp.StatusCode == http.StatusNotFound {
		return nil, nil // User not found
	}
	if resp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("API error: status %d", resp.StatusCode)
	}

	var data MetricsResponse
	if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
		return nil, err
	}
	return &data, nil
}

<?php

function getKulawiseMetrics(?string $username = null, ?string $email = null): ?array {
    $apiKey = getenv('KULAWISE_API_KEY');
    $query = $username ? ['username' => $username] : ['email' => $email];
    $url = 'https://api.kulawise.com/api/v1/partners/health-metrics?' . http_build_query($query);

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'X-Partner-Key: ' . $apiKey,
        'Accept: application/json'
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode === 404) {
        return null; // User not found
    }
    if ($httpCode !== 200) {
        throw new Exception("Kulawise API error: status {$httpCode}");
    }

    $data = json_decode($response, true);
    return $data['metrics'] ?? null;
}