Ouruka ID Service

Ouruka ist ein REST-API-Dienst zur Erzeugung eindeutiger, strukturierter IDs. Statt selbst Zähler, Datumslogik und Eindeutigkeitsgarantien zu bauen, definierst du ein Schema (z. B. ORD-{DATE:YYYY}-{COUNTER:6}) und rufst per API fertige IDs ab – fortlaufend, kollisionsfrei, auch unter hoher Last.

• Basis-URL: https://ouruka.com
• Authentifizierung: API-Key im Header X-API-KEY
• API-Referenz: /swagger/ (maschinenlesbar, interaktiv)

Typische Einsatzbereiche

• PIM: einheitliche Artikel- und Produktnummern über mehrere Kanäle hinweg.
• ERP: Beleg-, Auftrags- und Lieferscheinnummern in einheitlichem Format.
• E-Commerce: Bestell-, Kunden- und Transaktionsnummern.
• Logistik: Sendungsnummern, Paletten-IDs, Versandlabels.
• Healthcare: Patientenakten-, Proben- und Vorgangsnummern.
• Produktion: Serien-, Chargen- und Qualitäts-IDs.

Der Rest dieser Dokumentation führt Schritt für Schritt durch Authentifizierung, Schemas, alle Platzhalter, die Zusatzdienste (UID, Keyify, Mappings) und eine praxisnahe Beispiel-Bibliothek.

Schnellstart

In wenigen Schritten zur ersten generierten ID.

Schritt 1 — API-Key erhalten

Dein Zugang (Tenant) wird von Ouruka bereitgestellt; bei der Registrierung erhältst du einmalig einen api_key. Dieser Key identifiziert deinen Tenant und wird für alle Anfragen benötigt – sicher aufbewahren (siehe Authentifizierung).

Schritt 2 — Schema anlegen

Ein Schema definiert das Format deiner IDs. Du legst fest, aus welchen Bausteinen (Datum, Zähler, feste Zeichen, Variablen) sich eine ID zusammensetzt.

curl -X POST https://ouruka.com/v2/schemas \
  -H "X-API-KEY: $KEY" -H "Content-Type: application/json" \
  -d '{"name":"bestellung","pattern":"ORD-{DATE:YYYY}{DATE:MM}-{COUNTER:5}","start_value":1}'

Das erzeugt IDs im Format ORD-202601-00001.

Schritt 3 — ID generieren

Mit dem Schema-Namen rufst du die nächste ID ab. Ouruka stellt sicher, dass jede ID eindeutig ist.

curl -X POST https://ouruka.com/v2/generate/bestellung -H "X-API-KEY: $KEY"

{ "id": "ORD-202601-00001" }

Jeder weitere Aufruf liefert die nächste Nummer (…-00002, …-00003, …).

🔧 Tiefer erklärt: Die Eindeutigkeit garantiert der Server, nicht dein Code: Der Zähler wird atomar erhöht, sodass selbst tausende gleichzeitige Aufrufe (aus mehreren Systemen) nie dieselbe Nummer doppelt bekommen. Du musst dich also um Sperren, Locks oder Race Conditions nicht kümmern – ein einziger POST genügt pro ID.

Interaktiv ausprobieren: https://ouruka.com/swagger/ — dort „Authorize" klicken, API-Key eintragen und alle Endpunkte direkt im Browser testen.

Authentifizierung

Alle Endpunkte, die Daten lesen oder schreiben, erfordern einen gültigen API-Key im HTTP-Header:

X-API-KEY: <dein API-Key>

Ausnahmen (ohne Key erreichbar): GET /health und GET /v2/changelog.

Der API-Key identifiziert deinen Tenant eindeutig und steuert den Zugriff auf alle deine Schemas, Zähler, Mappings und History-Daten. Fehlt der Key oder ist er ungültig, antwortet der Dienst mit 401 Unauthorized.

🔧 Tiefer erklärt: Es gibt keinen „Passwort vergessen"-Weg – der Key ist zugleich Identität und Berechtigung, und Ouruka speichert ihn nur als SHA-256-Hash (der Klartext existiert also nur bei dir). Deshalb kann der Key nicht „ausgelesen" werden; ist er weg, erzeugst du über die Rotation einfach einen neuen. Intern gibt es zwei Ebenen: den Tenant-Key (deine Daten) und einen separaten Master-Key (nur das Ouruka-Backend, für Verwaltung) – die beiden sind strikt getrennt.

Sichere Handhabung

• Den API-Key nie im Quellcode oder in versionierten Dateien ablegen.
• Umgebungsvariablen oder Secret-Manager verwenden (z. B. AWS Secrets Manager, HashiCorp Vault, Kubernetes Secrets).
• Nicht an Dritte weitergeben – wer den Key kennt, kann in deinem Namen IDs generieren.
• Die Übertragung erfolgt ausschließlich über HTTPS/TLS.
• Ouruka speichert Keys nie im Klartext, sondern nur als kryptografischen Hash (SHA-256).

Key-Rotation

Falls ein Key kompromittiert wurde – oder rein vorsorglich – lässt er sich jederzeit rotieren. Der neue Key wird einmalig zurückgegeben, der alte wird sofort ungültig:

curl -X POST https://ouruka.com/v2/me/rotate-key -H "X-API-KEY: $KEY"

{ "status": "rotated", "api_key": "…neuer Key…",
  "message": "Der bisherige Key ist ab sofort ungültig." }

Den neuen Key sofort sicher speichern – er erscheint nur in dieser einen Antwort.

Schemas & Platzhalter

Ein Schema ist die Schablone für eine ID-Serie – du legst einmal fest, wie deine Nummern aussehen, und Ouruka liefert sie ab dann fortlaufend. Ein Muster (Pattern) besteht aus festem Text plus Platzhaltern, z. B. ART-{DATE:YY}{DATE:MM}-{COUNTER:4} → ART-2603-0017.

🔧 Tiefer erklärt: Ein Schema ist an einen Tenant gebunden und hat einen eigenen, unabhängigen Zähler, eigene History und ein eigenes Pattern. Schemas sind immutable: einmal angelegt, lässt sich das Pattern nicht mehr ändern (409 Conflict bei erneutem POST). Das ist Absicht – eine laufende Nummernserie soll ihr Format nicht mittendrin wechseln. Zum „Ändern" löscht man das Schema und legt es neu an (der Zähler startet dann wieder beim start_value).

Datums-Platzhalter

Setzen automatisch das aktuelle Datum ein – praktisch, um auf einen Blick zu sehen, wann etwas angelegt wurde.

Bunt gemischte Praxis:

🔧 Tiefer erklärt: Das Datum wird zur Generierungszeit in UTC aufgelöst (nicht beim Anlegen des Schemas). Ein Tages-Präfix wie {DATE:YYYY}{DATE:MM}{DATE:DD} eignet sich hervorragend als „Bucket" für Statistiken und Archivierung. Reihenfolge und Trennzeichen sind frei kombinierbar.

Zähler — {COUNTER:N}

Der Kern jeder fortlaufenden Nummer: ein hochzählender Zähler, der links mit Nullen aufgefüllt wird. N ist die Stellenzahl ({COUNTER:4} → 0001, 0002, …).

🔧 Tiefer erklärt: Der Zähler wird über ein atomares Redis-Verfahren erhöht – auch bei vielen gleichzeitigen Anfragen aus verschiedenen Systemen wird jeder Wert nur genau einmal vergeben (im Lasttest: 500.000 IDs, 0 Duplikate). N legt nur die Mindest-Breite fest: Bei mehr Nummern als Stellen wächst die Zahl mit ({COUNTER:4} liefert nach 9999 einfach 10000). Der optionale start_value (Standard 1) wird beim Schema-Anlegen gesetzt – ideal, um eine Nummernreihe aus einem Altsystem nahtlos fortzuführen.

Automatischer Reset (Intervall-Zähler)

Viele Nummernkreise sollen periodisch neu bei 1 beginnen (Rechnungsnummern pro Jahr, Tagestickets …). Ein angehängtes Intervall macht genau das – automatisch, ohne Cron-Job: {COUNTER:N:daily|monthly|quarterly|yearly}.

🔧 Tiefer erklärt: Technisch wird die aktuelle Periode Teil des Redis-Zähler-Keys (…:2026-03 für monatlich). Wechselt die Periode, entsteht ein neuer Key → der Zähler beginnt automatisch wieder beim start_value. Alte Perioden-Keys verfallen per TTL. Ein etwaiger start_value gilt bei jedem Reset (z. B. Reset auf 1000 statt 1).

Variablen — {VAR1} bis {VAR4}

Werte, die du pro Anfrage mitgibst (z. B. Ländercode, Produktgruppe) – so tragen deine IDs kontextspezifische Infos.

• {VAR1} – Wert direkt einfügen.
• {VAR1:-} / {VAR2:/} – Wert mit vorangestelltem Trenner (-, /, …).

🔧 Tiefer erklärt: Der Trenner erscheint nur, wenn der Wert nicht leer ist. Bleibt eine Variable leer, fallen Platzhalter und Trenner sauber weg – so entstehen keine doppelten Trennzeichen (ORD--0001). Damit lässt sich ein Pattern für „mit und ohne Zusatz" gleichzeitig nutzen. Übergabe im Request-Body: {"var1":"DE","var2":"B2B"}.

Mapping — {MAP:tabelle}

Übersetzt einen Klartext-Wert in einen Code: Du sagst „weiss", Ouruka setzt den hinterlegten Code „101" ein. So bleibt die Code-Zuordnung an einer Stelle statt in jedem System.

🔧 Tiefer erklärt: Mapping-Tabellen werden pro Tenant gepflegt (POST /v2/mappings/{tabelle}). Beim Generieren übergibst du den Klartext-Schlüssel; Ouruka löst ihn zur ID-Zeit auf. Ist der Wert nicht in der Tabelle, kommt 400 Bad Request mit klarer Meldung – so fällt ein Tippfehler sofort auf, statt eine falsche ID zu erzeugen. Ideal, wenn PIM, ERP und Shop denselben Farb-/Größencode brauchen.

Schema-Typ hash (Fingerprint)

Statt eines Zählers erzeugt ein Hash-Schema aus definierten Feldern einen immer gleichen Code für gleiche Eingaben – perfekt, um Dubletten zu erkennen.

{ "name": "fingerprint", "type": "hash", "fields": ["iban","name"], "hash_length": 64 }

🔧 Tiefer erklärt: Ouruka sortiert die Felder alphabetisch, verkettet sie als key=value|… und bildet einen SHA-256-Hash, gekürzt auf hash_length (erlaubt: 16, 32, 40, 64). Deshalb ist das Ergebnis deterministisch und reihenfolge-unabhängig: {"iban":"DE..","name":"ACME"} ergibt denselben Hash wie {"name":"ACME","iban":"DE.."}. Beim Generieren sind alle konfigurierten Felder Pflicht (sonst 400). Anwendungsfall: gleicher Lieferant/Datensatz → gleicher Fingerprint → als bereits bekannt erkennbar, ohne die Rohdaten im Klartext zu speichern.

Beispiel-Bibliothek

Konkrete Aufrufe für jede Funktion. Alle Beispiele nutzen https://ouruka.com als Basis und $KEY als Platzhalter für deinen Tenant-API-Key.

Alle geschützten Endpunkte erwarten den Header X-API-KEY: $KEY.

1. Authentifizierung

Jede Anfrage (außer /health und /v2/changelog) braucht deinen API-Key im Header:

curl https://ouruka.com/v2/me -H "X-API-KEY: $KEY"

Fehlt der Key oder ist er falsch, kommt 401 Unauthorized.

2. Schema anlegen (Muster)

Ein Schema ist die Schablone für eine ganze ID-Serie: Du legst das Muster einmal an, danach liefert jeder Generierungsaufruf die nächste ID daraus. Ein Schema ist nach dem Anlegen unveränderlich (ändern = löschen + neu anlegen) — so bleibt eine Nummernreihe in sich konsistent.

curl -X POST https://ouruka.com/v2/schemas \
  -H "X-API-KEY: $KEY" -H "Content-Type: application/json" \
  -d '{"name":"bestellung","pattern":"ORD-{DATE:YYYY}-{COUNTER:6}","start_value":1}'

Antwort (mit Vorschau der ersten ID, ohne den Zähler zu verbrauchen):

{ "name": "bestellung", "pattern": "ORD-{DATE:YYYY}-{COUNTER:6}", "preview": "ORD-2026-000001" }

Schemas auflisten & löschen

# Alle eigenen Schemas – inkl. Vorschau und zuletzt generierter ID
curl https://ouruka.com/v2/schemas -H "X-API-KEY: $KEY"

# Ein Schema löschen (entfernt auch dessen Zähler und History-Einträge)
curl -X DELETE https://ouruka.com/v2/schemas/bestellung -H "X-API-KEY: $KEY"

🔧 Tiefer erklärt: GET /v2/schemas liefert je Schema zusätzlich preview, last_generated und last_generated_at – gut für ein Dashboard. Da Schemas immutable sind, ist Löschen + neu anlegen der Weg, ein Pattern zu ändern; danach beginnt der Zähler wieder beim start_value.

3. IDs generieren

Einfacher Zähler mit Datum

curl -X POST https://ouruka.com/v2/generate/bestellung -H "X-API-KEY: $KEY"

{ "id": "ORD-2026-000001" }

Der nächste Aufruf liefert ORD-2026-000002, usw.

Startwert (z. B. Migration aus Altsystem)

Schema KND-{COUNTER:5} mit "start_value": 1000 → erste ID:

{ "id": "KND-01000" }

Zähler mit Auto-Reset (Intervall)

Viele Nummernkreise sollen periodisch neu bei 1 beginnen (z. B. Rechnungsnummern pro Jahr). Genau das macht ein Intervall-Zähler — automatisch, ohne Cron-Job oder manuellen Reset. Muster INV-{DATE:YYYY}-{COUNTER:5:yearly} setzt den Zähler jährlich zurück:

Unterstützte Intervalle: daily, monthly, quarterly, yearly.

Laufzeit-Variablen (mit optionalem Trenner)

Schema ART-{VAR1}-{VAR2}-{COUNTER:4}:

curl -X POST https://ouruka.com/v2/generate/artikel \
  -H "X-API-KEY: $KEY" -H "Content-Type: application/json" \
  -d '{"var1":"RED","var2":"XL"}'

{ "id": "ART-RED-XL-0001" }

Optionaler Trenner {VAR1:-}: ist die Variable leer, fallen Platzhalter und Trenner weg. Muster ORD-{DATE:YYYY}{VAR1:-}{COUNTER:5} → mit var1=DE: ORD-2026-DE-00001, ohne: ORD-2026-00001.

Attribut-Codes aus Mapping-Tabelle

Muster {COUNTER:4}{MAP:farbe} (Tabelle farbe: weiß→101):

curl -X POST https://ouruka.com/v2/generate/artikel \
  -H "X-API-KEY: $KEY" -H "Content-Type: application/json" \
  -d '{"mappings":{"farbe":"weiss"}}'

{ "id": "0001101" }

4. Hash-Schema (deterministischer Fingerprint)

Erzeugt aus definierten Feldern immer denselben Hash – ideal zur Dubletten-Erkennung.

curl -X POST https://ouruka.com/v2/schemas \
  -H "X-API-KEY: $KEY" -H "Content-Type: application/json" \
  -d '{"name":"fingerprint","type":"hash","fields":["iban","name"],"hash_length":64}'

Generieren (alle Felder sind Pflicht; Reihenfolge egal):

curl -X POST https://ouruka.com/v2/generate/fingerprint \
  -H "X-API-KEY: $KEY" -H "Content-Type: application/json" \
  -d '{"iban":"DE12...","name":"ACME GmbH"}'

{ "id": "9f2c4a1b…" }

Gleiche Eingabe → immer gleicher 64-Zeichen-Hash. Erlaubte Längen: 16, 32, 40, 64.

5. Zufalls-IDs (UID)

Ohne Schema, rein zufällig. Zwei Varianten, Längen 16 / 32 / 64 / 128 / 256 / 512.

curl -X POST https://ouruka.com/v2/uid/numeric \
  -H "X-API-KEY: $KEY" -H "Content-Type: application/json" -d '{"length":16}'

{ "id": "8391027465018273", "length": 16, "type": "numeric" }

/v2/uid/alpha liefert alphanumerische UIDs. In der History werden UIDs maskiert gespeichert (nur die letzten 5 Zeichen sichtbar).

6. Text zu Schlüssel (Keyify)

Wandelt beliebigen Text in einen URL-/systemsicheren Schlüssel um (Umlaute umgesetzt, Sonderzeichen entfernt).

curl -X POST https://ouruka.com/v2/keyify \
  -H "X-API-KEY: $KEY" -H "Content-Type: application/json" \
  -d '{"input":"Rote Größe – XÄ 42!"}'

{ "input": "Rote Größe – XÄ 42!", "key": "Rote_Groesse_XAe_42" }

7. Mapping-Tabellen

Mit Mapping-Tabellen musst du in der Anwendung nur den Klartext-Wert kennen (z. B. „weiss") — Ouruka setzt den hinterlegten Code (z. B. „101") beim Generieren ein. So bleiben Code-Zuordnungen zentral an einer Stelle, statt in jedem angebundenen System gepflegt zu werden. Zentrale Nachschlagetabellen (menschenlesbarer Wert → Code) für {MAP:...}.

# Eintrag anlegen/aktualisieren
curl -X POST https://ouruka.com/v2/mappings/farbe \
  -H "X-API-KEY: $KEY" -H "Content-Type: application/json" \
  -d '{"key":"weiss","value":"101"}'

# Alle Tabellen / Einträge einer Tabelle
curl https://ouruka.com/v2/mappings         -H "X-API-KEY: $KEY"
curl https://ouruka.com/v2/mappings/farbe   -H "X-API-KEY: $KEY"

# Einzelnen Eintrag / ganze Tabelle löschen
curl -X DELETE https://ouruka.com/v2/mappings/farbe/weiss -H "X-API-KEY: $KEY"
curl -X DELETE https://ouruka.com/v2/mappings/farbe       -H "X-API-KEY: $KEY"

8. History (mit Pagination)

curl "https://ouruka.com/v2/history?limit=50&offset=0" -H "X-API-KEY: $KEY"

[
  { "id": "ORD-2026-000002", "schema_name": "bestellung",
    "pattern_used": "ORD-{DATE:YYYY}-{COUNTER:6}",
    "requested_at": "2026-07-26T10:15:03.421Z", "source_ip": "203.0.113.7" }
]

Blättern: ?limit=50&offset=50 liefert die nächste Seite.

9. Eigene Daten & Limits

curl https://ouruka.com/v2/me -H "X-API-KEY: $KEY"

{
  "package": "Orbit",
  "limits": { "max_schemas": 5, "monthly_ids": 2000 },
  "usage":  { "schemas": 2, "ids_this_month": 341 }
}

10. API-Key rotieren

Erzeugt einen neuen Key; der alte wird sofort ungültig. Neuen Key sofort sicher speichern – er erscheint nur einmal.

curl -X POST https://ouruka.com/v2/me/rotate-key -H "X-API-KEY: $KEY"

{ "status": "rotated", "api_key": "…neuer Key…", "message": "Der bisherige Key ist ab sofort ungültig." }

11. Fehlerfälle im Überblick

Fehlerantworten sind JSON, z. B.:

{ "error": "Schema-Limit erreicht (5/5). Lösche ein bestehendes Schema oder wechsle das Paket." }

Zufalls-IDs (UID)

Manchmal willst du keine sprechende Nummer, sondern einfach einen eindeutigen Zufallscode – z. B. für Tokens, Gutschein-PINs oder anonyme Kennungen. Genau dafür sind UIDs: rein zufällig, ohne Datum oder Zähler.

🔧 Tiefer erklärt: UIDs tragen keine Semantik und brauchen kein Schema. Sie werden aus kryptografischem Zufall erzeugt; je länger, desto kleiner die (ohnehin winzige) Kollisionswahrschein- lichkeit. UIDs zählen zum monatlichen ID-Kontingent und werden in der History maskiert gespeichert (nur die letzten 5 Zeichen sichtbar) – so taucht ein sensibler Code nie vollständig im Log auf.

Erlaubte Längen: 16, 32, 64, 128, 256, 512. (Andere Werte → 400 Bad Request.)

Numerische UIDs — POST /v2/uid/numeric

Nur Ziffern (0–9) – gut, wenn Menschen den Code am Telefon durchgeben oder er in ein Zahlenfeld muss.

curl -X POST https://ouruka.com/v2/uid/numeric \
  -H "X-API-KEY: $KEY" -H "Content-Type: application/json" -d '{"length":16}'

{ "id": "8391027465018273", "length": 16, "type": "numeric" }

Alphanumerische UIDs — POST /v2/uid/alpha

Buchstaben + Ziffern (a–z, A–Z, 0–9) – kompakter und „unratbarer" bei gleicher Länge.

curl -X POST https://ouruka.com/v2/uid/alpha \
  -H "X-API-KEY: $KEY" -H "Content-Type: application/json" -d '{"length":32}'

🔧 Tiefer erklärt: Der alphanumerische Zeichenraum ist deutlich größer als der numerische – eine 16-stellige Alpha-UID ist damit weit „stärker" als eine 16-stellige Numeric-UID. Faustregel: numerisch für menschenfreundliche Codes, alphanumerisch für technische Schlüssel/Tokens. Für sicherheitskritische Secrets eher 64+ wählen.

String-Konvertierung (Keyify)

Keyify macht aus beliebigem Text einen sauberen, system-sicheren Schlüssel – z. B. aus einem Produktnamen einen technischen Bezeichner. Ein kleines, aber praktisches Werkzeug.

🔧 Tiefer erklärt: Keyify ist zustandslos (kein Schema, keine gespeicherte ID) und dient dazu, aus redaktionell gepflegten Klartexten konsistente, wiederholbare Schlüssel zu erzeugen – etwa für Datenbankschlüssel, interne Codes oder als Baustein vor der eigentlichen ID-Erzeugung. Gleiche Eingabe ergibt immer denselben Schlüssel.

POST /v2/keyify (auth-pflichtig).

Was passiert

• Leerzeichen → Unterstrich (_)
• Deutsche Umlaute aufgelöst: ä→ae, ö→oe, ü→ue, Ä→Ae, Ö→Oe, Ü→Ue, ß→ss
• sonstige Sonderzeichen werden entfernt
• Groß-/Kleinschreibung bleibt erhalten
• mehrfache Unterstriche werden zusammengefasst

curl -X POST https://ouruka.com/v2/keyify \
  -H "X-API-KEY: $KEY" -H "Content-Type: application/json" \
  -d '{"input":"Rote Größe – XÄ 42!"}'

{ "input": "Rote Größe – XÄ 42!", "key": "Rote_Groesse_XAe_42" }

Beispiele (bunt gemischt)

🔧 Tiefer erklärt: Deutsche Umlaute und ß werden gezielt transliteriert (ä→ae, ß→ss, …); übrige Sonderzeichen werden – soweit möglich auf einen Grundbuchstaben abgebildet, sonst – entfernt. Der Schlüssel besteht am Ende ausschließlich aus A–Z, a–z, 0–9 und _. Wer klein geschriebene URL-Slugs mit Bindestrichen braucht, wandelt das Ergebnis nachgelagert um – Keyify ist bewusst auf technische Schlüssel (Groß/Klein erhaltend, Unterstriche) ausgelegt.

History

Ouruka merkt sich jede erzeugte ID – so kannst du jederzeit nachschauen, welche IDs wann generiert wurden. Praktisch für Audits, Fehlersuche und Kontrollen auf Vollständigkeit.

🔧 Tiefer erklärt: Die History wird pro Tenant geführt und ist über die REST-API abrufbar. Sie ist ein Komfort-/Nachweis-Feature, kein Langzeitarchiv: Aufbewahrungsdauer und maximale Zeilenzahl hängen vom Paket ab, ältere Einträge werden automatisch bereinigt. Wer IDs dauerhaft braucht, ruft sie regelmäßig ab und speichert sie im eigenen System.

Pro Eintrag gespeichert:

• die generierte ID (UIDs werden maskiert, nur die letzten 5 Zeichen sichtbar),
• Schema-Name und verwendetes Pattern,
• Zeitstempel der Generierung (UTC),
• Quell-IP.

Abruf mit Pagination

curl "https://ouruka.com/v2/history?limit=50&offset=0" -H "X-API-KEY: $KEY"

[
  { "id": "ORD-2026-000002", "schema_name": "bestellung",
    "pattern_used": "ORD-{DATE:YYYY}-{COUNTER:6}",
    "requested_at": "2026-07-26T10:15:03.906071Z", "source_ip": "203.0.113.7" }
]

• limit: Anzahl Einträge (Standard 50, Maximum 200).
• offset: überspringt die ersten N Einträge – ?limit=50&offset=50 liefert die zweite Seite.
• Sortierung: neueste zuerst.

🔧 Tiefer erklärt: Für lange Listen kombinierst du limit und offset zum seitenweisen Laden („unendliches Scrollen"): Seite 1 = offset=0, Seite 2 = offset=50, usw. Die source_ip ist die echte Client-IP (aus X-Forwarded-For hinter dem Reverse-Proxy); Zeitstempel sind mikrosekunden-genau in UTC – zum Anzeigen ggf. in die lokale Zeitzone umrechnen.

Pakete & Limits

Jedes Konto hat ein Paket, das festlegt, wie viel du nutzen darfst – wie viele Schemas, wie viele IDs pro Monat usw. Vom kostenlosen Test bis zum großen Paket ist alles klar gestaffelt.

🔧 Tiefer erklärt: Limits werden serverseitig durchgesetzt. Der monatliche Verbrauch wird in Redis gezählt und zu Monatsbeginn zurückgesetzt; Schema- und Mapping-Limits gegen den aktuellen Bestand geprüft. Wird ein Limit erreicht, kommt eine klare 403-Antwort mit Hinweis – die Generierung schlägt also kontrolliert fehl, statt still Daten zu verlieren.

Jeder Tenant gehört zu einem Paket mit definierten Kontingenten.

Der monatliche ID-Verbrauch wird automatisch getrackt und zu Monatsbeginn zurückgesetzt.

Eigenen Verbrauch abrufen

curl https://ouruka.com/v2/me -H "X-API-KEY: $KEY"

{
  "package": "Orbit",
  "limits": { "max_schemas": 5, "monthly_ids": 2000, "max_mapping_tables": 1, "max_mapping_entries": 50 },
  "usage":  { "schemas": 2, "ids_this_month": 341, "mapping_tables": 1 }
}

Was passiert am Limit?

• Schema-Limit erreicht → POST /v2/schemas antwortet mit 403 und Hinweis.
• Monatliches ID-Limit erreicht → POST /v2/generate/... antwortet mit 403.
• Fehlerantworten sind JSON, z. B.:

{ "error": "Monatliches ID-Limit erreicht (2000/2000).",
  "upgrade_hint": "Upgrade auf Galaxy für mehr Kontingent." }

Die aktuellen Paketdetails und Preise stehen auf https://ouruka.com.

Sicherheit & Compliance

Dieses Kapitel beschreibt die technisch umgesetzten Sicherheitsmaßnahmen von Ouruka. Es ist eine faktische Beschreibung der Kontrollen im Quellcode und Betrieb – keine Zusicherung einer formalen Zertifizierung (z. B. ISO 27001, SOC 2). Wo Compliance-Rahmenwerke genannt werden, geht es um die Abbildung einzelner Anforderungen durch konkrete Maßnahmen.

Übertragungssicherheit

Der gesamte Verkehr läuft über HTTPS/TLS. Unverschlüsselte Verbindungen werden nicht bedient.

Warum kein „Ende-zu-Ende" – und warum das hier richtig so ist

Ende-zu-Ende-Verschlüsselung (E2E) kennt man von Messengern wie WhatsApp: Eine Nachricht wird auf dem Gerät des Absenders verschlüsselt und erst auf dem Gerät des Empfängers wieder lesbar – der Anbieter dazwischen sieht nur Kauderwelsch. Das funktioniert, weil ein Messenger nur ein Bote ist: Er trägt den versiegelten Umschlag weiter, ohne den Inhalt je kennen zu müssen.

Ouruka ist kein Bote, sondern ein Bäcker: Seine Aufgabe ist es, die ID auszurechnen – Muster lesen, Zähler hochzählen, Datum und Variablen zusammensetzen. Dafür muss der Dienst die Zutaten verstehen und das Ergebnis im Klartext erzeugen. Ein Bäcker, der die Zutaten nicht sehen darf, kann nicht backen – und ein ID-Dienst, der die Eingaben nicht lesen darf, kann keine strukturierte ID bauen. E2E ist für diese Art von Dienst also das falsche Werkzeug – nicht aus Bequemlichkeit, sondern prinzipbedingt.

Wichtiger ist, was tatsächlich schützt – und genau das ist umgesetzt bzw. verfügbar:

Kurz: Für einen rechnenden Dienst wie Ouruka ist nicht „der Server darf nichts sehen" das Ziel, sondern „so wenig wie möglich – sicher übertragen, sicher aufbewahrt, jederzeit löschbar". Genau das leisten wir.

Authentifizierung & Zugangsdaten

• API-Keys werden niemals im Klartext gespeichert, sondern ausschließlich als SHA-256-Hash. Der Roh-Key wird genau einmal (bei Erstellung bzw. Rotation) ausgegeben und danach nie wieder. Selbst ein Lesezugriff auf die Datenbank gäbe keine nutzbaren Schlüssel preis.
• Der administrative Master-Key wird timing-sicher verglichen (crypto/subtle.ConstantTimeCompare) – das verhindert das schrittweise Erraten per Zeitmessung.
• Der Master-Key existiert nur als Umgebungsvariable auf dem Server – nie im Quellcode oder im Repository – und wird nicht in Logs geschrieben.
• Keine Standard-/Hardcoded-Zugangsdaten: Ohne korrekt gesetzte Konfiguration (DB, Redis, Master-Key) startet der Dienst nicht. Es gibt keine „vergessenen" Hintertüren.

Berechtigungen & Missbrauchsschutz

• Zwei getrennte Ebenen: Tenant-Key (X-API-KEY) nur für die eigenen Daten, Master-Key (X-MASTER-KEY) für administrative Vorgänge. Kunden können sich nicht selbst registrieren.
• Privilegien-Grenze: Das interne Sonderpaket ohne Limits ist über die API nicht vergebbar (Antwort 403) – ausschließlich manuell im Backend.
• Rate-Limiting öffentlicher Endpunkte (60 Anfragen/Minute/IP) gegen Missbrauch und Überlastung.
• Key-Rotation als Reaktion auf kompromittierte Schlüssel: neuer Key sofort gültig, alter sofort ungültig – ohne Ausfallzeit.

Datenintegrität

• Zähler werden über ein atomares Redis-Verfahren erhöht – auch bei massiver Nebenläufigkeit wird jeder Wert nur einmal vergeben (im Lasttest: 500.000 IDs, 0 Duplikate).
• Schemas sind unveränderlich – eine laufende Nummernserie kann nicht nachträglich umdefiniert werden.
• Eingaben werden validiert (z. B. erlaubte UID-/Hash-Längen, Muster, Mapping-Schlüssel).

Datenschutz (Privacy by Design)

• Datenminimierung: Kein Benutzername/Passwort-System; der API-Key ist zugleich Identität. Es werden keine unnötigen personenbezogenen Daten erhoben.
• Maskierung: Zufalls-UIDs werden in der History nur maskiert gespeichert (letzte 5 Zeichen sichtbar).
• Recht auf Löschung: Beim Löschen eines Tenants werden alle zugehörigen Daten (Schemas, History, Zähler, Mappings) kaskadierend entfernt.
• Zeitstempel werden konsistent in UTC gespeichert.

Nachvollziehbarkeit (Auditability)

• Jede Anfrage erhält eine eindeutige X-Request-ID, die in strukturierten JSON-Logs erscheint – Grundlage für Fehleranalyse, Monitoring und Audits.

Abbildung auf gängige Anforderungen

Die obigen Maßnahmen adressieren u. a. folgende, häufig geprüfte Prinzipien (ohne Anspruch auf Vollständigkeit oder Zertifizierung):

FAQ

Sind die IDs wirklich eindeutig?

Ja. Ouruka garantiert Eindeutigkeit innerhalb eines Schemas (Schema-IDs) bzw. innerhalb eines Tenants (UIDs). Zähler werden atomar inkrementiert – auch bei parallelen Anfragen wird jeder Zählerwert nur einmal vergeben. Belegt durch Lasttests: 500.000 IDs unter Volllast, 0 Duplikate.

Was passiert, wenn zwei Systeme gleichzeitig eine ID anfordern?

Ouruka nutzt eine atomare Zähler-Operation (Redis-Lua-Script), die Race Conditions ausschließt. Selbst zwei Anfragen in derselben Millisekunde erhalten unterschiedliche, eindeutige IDs.

Kann ich den Zähler zurücksetzen?

Es gibt keinen separaten Reset-Endpunkt. Für periodisches Zurücksetzen nutzt du einen Intervall-Zähler ({COUNTER:N:yearly} etc.) – der setzt sich automatisch zurück. Ein einmaliger Reset ist über Schema löschen + neu anlegen möglich (der Zähler startet dann wieder beim start_value). Achtung: Bei unverändertem Pattern können dabei bereits vergebene Werte erneut entstehen – in dem Fall zusätzlich das Pattern anpassen (z. B. Jahresteil oder festes Präfix).

Was ist der Unterschied zwischen Schema-IDs und UIDs?

Schema-IDs folgen einem selbst definierten Pattern und können lesbare Informationen tragen (Datum, Zähler, Variablen) – ideal für Beleg- oder Produktnummern. UIDs sind rein zufällig und bedeutungsfrei – ideal für technische Schlüssel und Tokens.

Wie sicher ist der API-Key?

Übertragung nur über HTTPS; Keys werden nie im Klartext gespeichert (nur als SHA-256-Hash); der Vergleich läuft timing-sicher. Bei Verdacht auf Kompromittierung lässt sich der Key sofort rotieren. Key stets außerhalb des Quellcodes aufbewahren.

Kann ich mehrere Schemas haben?

Ja, je nach Paket. Jedes Schema hat einen eigenen unabhängigen Zähler, eigene History und eigenes Pattern – typischerweise ein Schema pro Dokumententyp (Bestellungen, Rechnungen, Kunden …).

Was passiert, wenn ein Variablen-Wert leer ist?

Der Platzhalter wird durch einen leeren String ersetzt; bei Separator-Syntax ({VAR1:-}) fällt auch der Trenner weg – keine doppelten Trennzeichen. Datums-Platzhalter sind nie leer (immer Systemdatum).

Wie hoch ist die Performance?

ID-Generierung wird typischerweise im zweistelligen bis niedrigen dreistelligen Millisekundenbereich beantwortet; im Lasttest wurden 1.000+ IDs/Sekunde bei 0 Fehlern und 0 Duplikaten gemessen. Für konkrete SLA-Anforderungen den Support kontaktieren.

Lässt sich Ouruka einfach integrieren?

Ja. Standard-REST-API mit JSON – nur HTTP-Requests nötig, keine SDK-Abhängigkeiten, keine proprietären Protokolle. Jede Sprache, die HTTP kann, ist kompatibel (Python, Java, PHP, JavaScript …), ebenso Low-Code-Plattformen wie Make oder Zapier.

API-Referenz (Swagger)

Die vollständige, maschinenlesbare API-Referenz ist interaktiv verfügbar unter:

https://ouruka.com/swagger/

Dort findest du:

• Alle Endpunkte mit Methoden, Pfaden und Beschreibungen.
• Request-/Response-Schemas inkl. Datentypen und Pflichtfeldern.
• Interaktives Testen direkt im Browser – auf „Authorize" klicken, X-API-KEY eintragen, Endpunkte ausprobieren.
• Fehlercodes und ihre Bedeutung.

Endpunkt-Überblick

Open-Source-Komponenten & Audit

Diese Übersicht dient als Software Bill of Materials (SBOM) und als Ausgangspunkt für einen Open-Source-Audit. Sie listet alle Dritt-Komponenten, aus denen Ouruka besteht bzw. die es zur Laufzeit nutzt, samt Version und Lizenz.

Hinweis zur Verbindlichkeit: Die Lizenzangaben entsprechen dem allgemeinen Kenntnisstand zu den jeweiligen Projekten. Für ein formales Audit sollte zusätzlich ein automatischer Lizenz-/SBOM-Scan laufen (siehe Reproduzieren) und im Zweifel die jeweilige LICENSE-Datei geprüft werden.

Die Applikation selbst

In das Service-Binary kompilierte Go-Module

Ermittelt aus dem gebauten Binary (go version -m) – das ist die verbindliche Laufzeit-Stückliste.

Funktional relevant zur Laufzeit sind primär lib/pq und redis/go-redis; der Rest bedient den eingebetteten /swagger/-Endpunkt. Nur zur Entwicklung/Test (nicht im Binary): stretchr/testify, bsm/ginkgo, bsm/gomega, google/go-cmp.

Container-Images (Betrieb)

Drittsysteme (Betrieb)

• PostgreSQL 16 – persistente Speicherung. Lizenz: PostgreSQL License (permissiv).
• Redis 7.4 – atomare Zähler und Rate-Limit-Buckets. Lizenz: RSALv2/SSPLv1 (siehe Befund).
• Reverse-Proxy / TLS-Terminierung (Infrastruktur, außerhalb dieses Repos).

Befunde für den Auditor

1. ⚠️ Redis 7.4.8 ist nicht mehr OSI-Open-Source. Ab Redis 7.4 gilt die duale Lizenz RSALv2 / SSPLv1 (source-available). Für den reinen Eigenbetrieb als Abhängigkeit ist das i. d. R. unkritisch, ein OSS-Audit wird es aber als Nicht-OSS-Komponente kennzeichnen. Entscheidung: Ouruka setzt bewusst weiter auf Redis – für den Eigenbetrieb erlaubt und kostenlos. Sollte je eine strikte „nur OSI-Open-Source"-Anforderung bestehen, gäbe es zwei einfache Alternativen (redis:7.2-alpine, noch BSD-3-Clause, oder der kompatible Fork Valkey); beide werden aktuell nicht benötigt.
2. Alpine-Basis enthält GPLv2-Komponenten (BusyBox, apk-tools). Sie werden als unveränderte Betriebssystem-Basis genutzt und nicht in die Applikation gelinkt – Standardpraxis, aber auflisten.
3. Alle in das Binary kompilierten Go-Module sind permissiv (MIT / BSD / Apache-2.0). Kein Copyleft (GPL/LGPL) im Applikations-Binary.
4. Versions-Pinning: redis:7, postgres:16 folgen dem Major-Tag (floaten innerhalb Major). Für ein Audit exakte Versionen bzw. Image-Digests festschreiben.

In Klartext: warum wir den Redis-Punkt offen zeigen

Wir könnten diesen Punkt verstecken – tun wir bewusst nicht. Offenheit ist für uns ein Qualitätsmerkmal, kein Risiko.

Redis ist ein fertiger Baustein eines anderen Herstellers, den Ouruka als schnelles „Zählwerk" nutzt. Jede Software kommt mit einer Lizenz – den Spielregeln der Nutzung. Redis hatte lange die freizügigste Sorte (jeder darf alles). 2024 haben die Macher die Regeln ab Version 7.4 geändert: jetzt „source-available" – der Code bleibt einsehbar und für den Eigenbetrieb weiterhin kostenlos und erlaubt, gilt aber offiziell **nicht mehr als „echtes Open Source". Die Einschränkung zielt auf große Cloud-Anbieter, die Redis als eigenen Bezahldienst weiterverkaufen – nicht auf Nutzer wie uns.

Bild dazu: Ein Spezial-Ofen im Restaurant, dessen Hersteller die Bedingungen von „benutz ihn frei" auf „benutzen ja – aber kein Ofen-Vermietgeschäft damit" ändert. Fürs Kochen ändert sich nichts; ein Prüfer notiert den Punkt trotzdem.

Für uns bedeutet das: erlaubt, kostenlos, im Betrieb unproblematisch. Ein formaler OSS-Audit markiert die Komponente zwar als „kein Standard-Open-Source" – wir setzen aber bewusst weiter auf Redis und legen den Punkt hier offen dar. Falls je eine strikte „nur OSI-Open-Source"-Anforderung aufkommt, gibt es mit Valkey (technisch austauschbarer Fork) oder Redis 7.2 zwei einfache Wege – aktuell nicht nötig.

Reproduzieren des SBOMs

# Laufzeit-Stückliste des Binaries (verbindlich):
go build -o /tmp/ouruka . && go version -m /tmp/ouruka

# Vollständiger Modulgraph:
go list -m all

# Konkrete Dienst-Versionen im Betrieb:
docker exec ouruka-postgres postgres --version
docker exec ouruka-redis    redis-server --version

Empfohlen für ein formales Audit (nicht im Repo installiert): eine maschinenlesbare SBOM erzeugen, z. B. mit cyclonedx-gomod mod -json (CycloneDX) oder syft bzw. trivy für Go und Container-Images, sowie ein Lizenz-Scan mit go-licenses report ./....