API-Schlüssel — tnea_ & tnsr_¶

NumerologyAPI verwendet zwei Familien von API-Schlüsseln. Beide sehen ähnlich aus, werden im selben 80-stelligen sicheren Format erzeugt und authentifizieren mit demselben X-API-Key-Header — sie werden jedoch unterschiedlich abgerechnet und sind für unterschiedliche Produkte gedacht.

1. Schlüsselformat & Sicherheit¶

Jeder Schlüssel ist exakt 80 Zeichen lang:

tnea_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
tnsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Das 4-stellige Präfix kennzeichnet den Schlüsseltyp; die restlichen 75 Zeichen werden aus einer kryptografisch sicheren Zufallsquelle erzeugt.
• Schlüssel werden serverseitig SHA-256-gehasht gespeichert. Der Klartextschlüssel wird nur einmal angezeigt, bei der Erstellung.
• Falls ein Schlüssel jemals offengelegt wird, rotieren Sie ihn sofort über das Dashboard.

2. Plattformschlüssel (tnea_)¶

Plattformschlüssel sind die Standard-Schlüssel für die Integration von NumerologyAPI in Ihr eigenes Produkt — Websites, mobile Apps und serverseitige Dienste.

Authentifizierung¶

Senden Sie den Schlüssel bei jeder Anfrage mit dem X-API-Key-Header:

curl --request GET \
  --url "https://api.numerologyapi.com/api/v1/life_path?birth_year=1990&birth_month=5&birth_day=15" \
  --header "x-api-key: tnea_YOUR_API_KEY"

Abrechnung¶

Abrechenbare /api/v1-Aufrufe werden vom Credits-Wallet Ihrer Organisation (Pay-as-you-go) abgezogen. Sie können das Wallet jederzeit über das Dashboard aufladen.

Kanalregel: Plattformschlüssel dürfen den X-Numora-Client-Header nicht senden. Das Senden führt zu 403 — dieser Header ist dem Desktop-Kanal vorbehalten.

3. Numora-Studio-Schlüssel (tnsr_)¶

Numora-Studio-Schlüssel authentifizieren die Numora-Studio-Desktop-App (macOS/Windows), die von Praktikern zur Erstellung von Kundenberichten verwendet wird. Sie sind Geschwister der Plattformschlüssel mit identischem Format, werden jedoch gegen das Kontingent des Numora-Studio-Plans der Organisation abgerechnet statt gegen Plattform-Credits.

Bereitstellung¶

Ein tnsr_-Schlüssel wird entweder erstellt:

• über den Anmeldevorgang der Desktop-App (die Browser-Zustimmungsseite stellt automatisch einen Schlüssel bereit), oder
• manuell auf der Seite API-Schlüssel im Dashboard (/api-keys).

Kanalsignatur (verpflichtend)¶

Jeder Aufruf mit einem tnsr_-Schlüssel muss den Desktop-Kanal-Header enthalten:

Serverdurchsetzung:

• tnsr_-Schlüssel ohne X-Numora-Client → 403.
• tnea_-Schlüssel mit X-Numora-Client → 403.

Abrechnung¶

• Abrechenbare /api/v1-Aufrufe werden vom Kontingent des Numora-Studio-Plans der Organisation abgezogen (ein gemeinsamer Pool für alle tnsr_-Schlüssel der Organisation).
• Pro tnsr_-Schlüssel gibt es einen Credit-Fallback-Umschalter: Wenn das Plan-Kontingent erschöpft ist, kann der Schlüssel auf die Plattform-Credits der Organisation zurückfallen (standardmäßig deaktiviert).
• Wenn das Kontingent erschöpft ist und kein Fallback aktiviert ist, geben Aufrufe 429 zurück.

Gerätesperre (optional)¶

Ein tnsr_-Schlüssel kann an registrierte Geräte gebunden werden. Bei aktivierter Sperre muss jede Anfrage eine bei der Organisation registrierte X-Numora-Device-Id enthalten; nicht registrierte Geräte werden mit 403 abgelehnt.

Desktop-exklusive Endpunkte¶

Einige Endpunkte sind dem Desktop-Kanal vorbehalten und geben für tnea_- Schlüssel 403 zurück:

• POST /api/v1/numora/report-bundle — vollständiger Kundenbericht in einem Aufruf
• POST /api/v1/numora/order — In-App-Kaufvorgang für Plan/Kontingent
• POST /api/v1/numora/devices/register — Desktop-Installation registrieren
• GET /api/v1/numora/studio-status — Desktop-Guthaben und Quotenmesswerte

Tipp: Abrechenbare Antworten enthalten außerdem die Header X-Remaining-Credits und X-Remaining-Tokens, sodass Sie Live-Guthaben ohne zusätzliche Aufrufe verfolgen können.

4. Schlüssel verwalten (Dashboard)¶

Die Seite API-Schlüssel im Dashboard (/api-keys) ist die Kommandozentrale für beide Schlüsseltypen.

Rollen: Die Rollen admin und developer können Schlüssel erstellen und verwalten. finance kann keine Produktions-API-Schlüssel erstellen. Finanzielle Vorgänge (Plankäufe, Aufladungen) sind auf admin und finance beschränkt.

Mehrere Schlüssel: Organisationen können viele Schlüssel beider Typen halten — zum Beispiel einen tnsr_-Schlüssel pro Praktiker oder pro Desktop-Installation. Kontingente werden pro Organisation geteilt, sodass Schlüssel nie um ein eigenes Guthaben „konkurrieren".

5. Best Practices¶

• Behandeln Sie Schlüssel wie Passwörter. Betten Sie sie niemals in clientseitigen Code, öffentliche Repositories oder Logs ein.
• Verwenden Sie Umgebungsvariablen oder einen Secrets-Manager in Ihrem Backend.
• Rotieren Sie sofort, wenn ein Schlüssel kompromittiert ist oder ein Teammitglied das Team verlässt.
• Verwenden Sie einen tnsr_-Schlüssel pro Desktop-Installation, um Geräteverwaltung und Widerruf zu vereinfachen.
• Aktivieren Sie die Gerätesperre für Organisationen mit hohen Sicherheitsanforderungen.
• Überwachen Sie die Nutzung im Dashboard, um unerwartete Spitzen früh zu erkennen.

6. Häufige Fragen¶

Kann ein tnsr_-Schlüssel reguläre Plattform-Endpunkte aufrufen? Ja. Numora-Studio-Schlüssel authentifizieren die gesamte /api/v1-Oberfläche; diese Aufrufe werden gegen das Kontingent des Numora-Studio-Plans abgerechnet.

Kann ein tnea_-Schlüssel Desktop-exklusive /numora/*-Endpunkte aufrufen? Nein. Desktop-exklusive Endpunkte geben für Plattformschlüssel 403 zurück.

Warum erhalte ich 403, wenn ich mit meinem tnsr_-Schlüssel aufrufe? Wahrscheinlich fehlt der X-Numora-Client-Header oder die App-ID stimmt nicht überein. Stellen Sie sicher, dass jede Anfrage X-Numora-Client: numora-studio/<version> enthält.

Warum erhalte ich 403 mit meinem tnea_-Schlüssel? Plattformschlüssel dürfen den X-Numora-Client-Header nicht tragen — entfernen Sie ihn.

Was passiert, wenn mein Kontingent aufgebraucht ist? Abrechenbare Aufrufe geben 429 zurück, es sei denn, der Credit-Fallback ist für Ihren tnsr_-Schlüssel aktiviert (oder Sie laden Ihr Plattform-Wallet für tnea_-Schlüssel auf).

Verwandte Themen¶

• Erste Schritte
• Preise
• Unternehmenslösungen