Ticos Update-Portal — Client-API

Überblick

JSON-REST-API über HTTPS. Ein Client fragt die neueste Version eines Channels ab, vergleicht sie mit der lokal installierten, lädt bei Bedarf das passende Artefakt über eine signierte Download-URL und verifiziert es per Prüfsumme (optional Signatur).

Authentifizierung

Jeder Client erhält im Admin einen persönlichen API-Token. Dieser wird bei jeder Anfrage im Header mitgeschickt:

Authorization: Bearer <DEIN_TOKEN>
Accept: application/json

Ein Client sieht ausschliesslich die Apps/Channels, die ihm zugeordnet sind. Inaktive Clients werden abgewiesen.

Endpunkte

{app} und {channel} sind die jeweiligen Slugs (z. B. t4000-uct, stable).

1) Update prüfen — latest

Optionale Query-Parameter platform (windows | android | linux | macos | …) und arch (x64 | arm64 | …) filtern die zurückgegebenen Artefakte.

curl -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
  "https://updates.ticos-systems.cloud/api/v1/apps/t4000-uct/channels/stable/latest?platform=android&arch=arm64"

Antwort:

{
  "data": {
    "version": "2.0.0",
    "version_code": 20000,
    "title": "Release 2.0.0",
    "release_notes": "# 2.0.0\n- Neuerungen …",
    "is_mandatory": false,
    "min_supported_version": null,
    "released_at": "2026-06-05T12:00:00+00:00",
    "channels": ["stable"],
    "artifacts": [
      {
        "id": 12,
        "platform": "android",
        "arch": "arm64",
        "file_type": "apk",
        "filename": "ticosuct-v20000-2.0.0.apk",
        "size": 19625198,
        "sha256": "7ff426bb…",
        "signature": "base64…",
        "signature_type": "ed25519",
        "download_url": "https://updates.ticos-systems.cloud/api/v1/download/12?client=1&expires=…&signature=…"
      }
    ]
  },
  "app": "t4000-uct",
  "channel": "stable"
}

Gibt es keine veröffentlichte Version im Channel, kommt 404.

2) Versionsliste

curl -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
  "https://updates.ticos-systems.cloud/api/v1/apps/t4000-uct/channels/stable/versions"

Liefert eine paginierte Liste (data, links, meta) mit version, version_code, title, is_mandatory, released_at.

3) Versionsdetails

curl -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
  "https://updates.ticos-systems.cloud/api/v1/apps/t4000-uct/versions/2.0.0"

4) Download & Verifikation

Die download_url aus der Antwort ist eine signierte, zeitlich begrenzte URL (900 Sekunden). Einfach per GET laden (Resume/Range wird unterstützt):

# herunterladen
curl -L -o update.apk "<download_url>"

# Prüfsumme verifizieren (muss mit "sha256" aus der Antwort übereinstimmen)
sha256sum update.apk

Signatur prüfen (optional, empfohlen)

Ist ein Artefakt signiert (signature_type: "ed25519"), kann die Echtheit gegen den folgenden öffentlichen Schlüssel (Ed25519, base64) geprüft werden:

OuVGyoQRnZ+I0UQS3EZfnMvEccl88i+/mmAyspO9I4I=

Die signature ist eine detached-Signatur (base64) über die unveränderten Dateibytes — verifizierbar z. B. mit libsodium crypto_sign_verify_detached.

5) Check-in (Telemetrie, optional)

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"app":"t4000-uct","installed_version":"2.0.0","channel":"stable","platform":"android","os_version":"Android 14"}' \
  "https://updates.ticos-systems.cloud/api/v1/checkin"
# → {"status":"ok"}

Empfohlener Ablauf im Client

1. latest für den passenden Channel abrufen.
2. version_code (bzw. version) mit der lokal installierten vergleichen.
3. Bei neuerer Version: passendes Artefakt wählen, download_url laden.
4. Datei gegen sha256 (und ggf. signature) verifizieren, dann installieren.
5. Bei is_mandatory: true das Update erzwingen.
6. Optional checkin melden.

Fehlercodes