API-sleutels — tnea_ & tnsr_¶

NumerologyAPI gebruikt twee families API-sleutels. Beide zien er hetzelfde uit, worden gegenereerd met hetzelfde veilige 80-tekensformaat en authenticeren met dezelfde X-API-Key header — maar ze worden anders afgerekend en zijn bedoeld voor verschillende producten.

1. Sleutelformaat & beveiliging¶

Elke sleutel is precies 80 tekens lang:

tnea_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
tnsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• De 4-tekensprefix bepaalt het sleuteltype; de overige 75 tekens worden gegenereerd met een cryptografisch beveiligde willekeurige bron.
• Sleutels worden SHA-256 gehasht aan de serverzijde opgeslagen. De leesbare sleutel wordt slechts één keer getoond, bij het aanmaken.
• Als een sleutel ooit is blootgesteld, roteer deze dan onmiddellijk via het dashboard.

2. Platform-sleutels (tnea_)¶

Platform-sleutels zijn de standaardsleutels voor het integreren van NumerologyAPI in je eigen product — websites, mobiele apps en server-side diensten.

Authenticatie¶

Stuur de sleutel bij elke aanvraag mee met de 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"

Afrekening¶

Factureerbare /api/v1-aanroepen worden afgetrokken van de credits-wallet van je organisatie (pay-as-you-go). Je kunt de wallet op elk moment via het dashboard opwaarderen.

Kanaalregel: platform-sleutels mogen geen X-Numora-Client header meesturen. Het versturen ervan geeft 403 — die header is gereserveerd voor het desktopkanaal.

3. Numora Studio-sleutels (tnsr_)¶

Numora Studio-sleutels authenticeren de Numora Studio desktopapp (macOS/Windows) die door behandelaars wordt gebruikt om cliëntrapporten te genereren. Ze zijn een tegenhanger van platform-sleutels met een identiek formaat, maar worden afgerekend tegen de toelage van het Numora Studio-abonnement van de organisatie in plaats van platformcredits.

Inrichting (provisioning)¶

Een tnsr_-sleutel wordt aangemaakt via:

• het aanmeldproces van de desktopapp (de browser-toestemmingspagina richt automatisch een sleutel in), of
• handmatig op de pagina API Keys van het dashboard (/api-keys).

Kanaalhandtekening (verplicht)¶

Elke aanroep met een tnsr_-sleutel moet de desktopkanaalheader bevatten:

Serverafdwinging:

• tnsr_-sleutel zonder X-Numora-Client → 403.
• tnea_-sleutel met X-Numora-Client → 403.

Afrekening¶

• Factureerbare /api/v1-aanroepen worden afgetrokken van de toelage van het Numora Studio-abonnement van de organisatie (één gedeelde pool voor alle tnsr_-sleutels van de organisatie).
• Er bestaat een credit-fallback-schakelaar per tnsr_-sleutel: wanneer de abonnementstoelage is verbruikt, kan de sleutel terugvallen op de platformcredits van de organisatie (standaard uitgeschakeld).
• Als de toelage is verbruikt en er geen fallback is ingeschakeld, geven aanroepen 429 terug.

Apparaatvergrendeling (optioneel)¶

Een tnsr_-sleutel kan worden vergrendeld aan geregistreerde apparaten. Met vergrendeling ingeschakeld moet elke aanvraag een X-Numora-Device-Id meesturen dat bij de organisatie is geregistreerd; niet-geregistreerde apparaten worden geweigerd met 403.

Desktop-exclusieve endpoints¶

Sommige endpoints zijn gereserveerd voor het desktopkanaal en geven 403 terug voor tnea_-sleutels:

• POST /api/v1/numora/report-bundle — volledig cliëntrapport in één aanroep
• POST /api/v1/numora/order — aankoopproces voor abonnement/toelage in de app
• POST /api/v1/numora/devices/register — een desktopinstallatie registreren
• GET /api/v1/numora/studio-status — desktopsaldi en quotummeters

Tip: factureerbare antwoorden bevatten ook de X-Remaining-Credits- en X-Remaining-Tokens-headers, zodat je live saldi kunt volgen zonder extra aanroepen.

4. Sleutels beheren (Dashboard)¶

De pagina API Keys van het dashboard (/api-keys) is het centrale beheerpunt voor beide sleuteltypen.

Rollen: de rollen admin en developer kunnen sleutels aanmaken en beheren. finance kan geen productie-API-sleutels aanmaken. Financiële bewerkingen (abonnementsaankopen, opwaarderingen) zijn beperkt tot admin en finance.

Meerdere sleutels: organisaties kunnen veel sleutels van beide typen beheren — bijvoorbeeld één tnsr_-sleutel per behandelaar of per desktopinstallatie. Toelages worden per organisatie gedeeld, dus sleutels "concurreren" nooit om een eigen saldo.

5. Beste praktijken¶

• Behandel sleutels als wachtwoorden. Verwerk ze nooit in client-side code, openbare repositories of logs.
• Gebruik omgevingsvariabelen of een secrets manager in je backend.
• Roteer onmiddellijk als een sleutel is gecompromitteerd of een teamlid vertrekt.
• Gebruik één tnsr_-sleutel per desktopinstallatie om apparaatbeheer en intrekking te vereenvoudigen.
• Schakel apparaatvergrendeling in voor organisaties met hoge beveiligingseisen.
• Houd het gebruik in de gaten in het dashboard om onverwachte pieken vroegtijdig op te merken.

6. Veelgestelde vragen¶

Kan een tnsr_-sleutel reguliere platform-endpoints aanroepen? Ja. Numora Studio-sleutels authenticeren het volledige /api/v1-oppervlak; die aanroepen worden afgerekend tegen de toelage van het Numora Studio-abonnement.

Kan een tnea_-sleutel desktop-exclusieve /numora/*-endpoints aanroepen? Nee. Desktop-exclusieve endpoints geven 403 terug voor platform-sleutels.

Waarom krijg ik 403 bij het aanroepen met mijn tnsr_-sleutel? Hoogstwaarschijnlijk ontbreekt de X-Numora-Client header of komt de app-id niet overeen. Controleer of elke aanvraag X-Numora-Client: numora-studio/<version> bevat.

Waarom krijg ik 403 met mijn tnea_-sleutel? Platform-sleutels mogen de X-Numora-Client header niet dragen — verwijder die.

Wat gebeurt er als mijn toelage op is? Factureerbare aanroepen geven 429 terug, tenzij credit-fallback is ingeschakeld op je tnsr_-sleutel (of je de platform-wallet opwaardeert voor tnea_-sleutels).

Gerelateerd¶

• Aan de slag
• Prijzen
• Enterprise Oplossingen