KAKEL Tech
Get started

Companion docs

Android-side post-sale provenance + stolen-recovery. White-label APK; HMAC-signed intake; AWS KMS encryption of secrets at rest.

Overview

The Companion APK installs at the point of sale or activation. It generates an EC P-256 keypair on-device (TEE-bound on Knox hardware), signs intake metadata (IMEI, Build.SERIAL, photos), and uploads it to the KAKEL backend over HMAC-signed HTTPS.

Two operational modes:

  • Intake — capture device identity at sale
  • Recovery — file stolen-device reports; remote lock; evidence-bundle PDF

Intake flow

On first launch the APK guides the customer through:

  1. Generate device keypair (one-tap; Knox TEE on supported hardware)
  2. Capture IMEI(s) automatically; Build.SERIAL captured automatically
  3. Capture device photo (optional but recommended for evidence packets)
  4. Capture customer phone + email + display name
  5. Sign + upload to POST /api/companion/intake

The server stores: public-key fingerprint, IMEI, deviceSerial, capturedAt timestamp, signature, signatureValid flag. Customer photos go to S3 with per-tenant prefix.

Stolen-device report

When a device is reported stolen, the customer files via the same APK. State machine:

OPEN → INVESTIGATING → RECOVERED
                  ↘ ESCALATED → BLACKLISTED → CLOSED

OPEN: Customer files. Includes circumstances, last-known location, police-report ID.

INVESTIGATING: KAKEL operations review.

ESCALATED: Severity-1 reports proceed to GSMA Device Check blacklist submission (requires KAKEL GSMA enrollment) and evidence-PDF generation.

BLACKLISTED / RECOVERED: Terminal states.

HMAC API key integration (for PhoneToolkit recipes)

PhoneToolkit's desktop recipes call back to the Companion API to look up prior records. The HMAC key pair is provisioned per-store from account → licenses.

Signing format for a request:

ts = unix_seconds()
mac = hmac_sha256(key_secret, ts + "\n" + body).hex()

Authorization: Companion <key_public_id>:<mac>
X-Companion-Timestamp: <ts>
X-Companion-Version: 1

Body is empty for GET requests. The server enforces a 5-minute timestamp window to prevent replay.

White-label theming

The APK supports OEM rebranding: replace the KAKEL logo, primary color, vendor name, and contact-support URL via the white-label config submitted at provisioning time. Each OEM gets their own backend instance with isolated tenant data.

Contact sales@kakel.io for white-label inquiries.