Chei API — tnea_ & tnsr_¶

NumerologyAPI folosește două familii de chei API. Ambele arată similar, sunt generate cu același format securizat de 80 de caractere și se autentifică cu același antet X-API-Key — dar sunt contorizate diferit și sunt destinate unor produse diferite.

1. Formatul și securitatea cheilor¶

Fiecare cheie are exact 80 de caractere:

tnea_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
tnsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Prefixul de 4 caractere identifică tipul cheii; restul de 75 de caractere sunt generate dintr-o sursă aleatorie securizată criptografic.
• Cheile sunt stocate hash-uite SHA-256 pe partea de server. Cheia în text clar este afișată doar o singură dată, la momentul creării.
• Dacă o cheie este vreodată expusă, rotiți-o imediat din dashboard.

2. Chei de platformă (tnea_)¶

Cheile de platformă sunt cheile standard pentru integrarea NumerologyAPI în propriul dvs. produs — site-uri web, aplicații mobile și servicii server-side.

Autentificare¶

Trimiteți cheia la fiecare solicitare cu antetul X-API-Key:

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"

Contorizare¶

Apelurile /api/v1 facturabile sunt deduse din portofelul de credite al organizației (plată la utilizare). Puteți încărca portofelul oricând din dashboard.

Regula canalului: cheile de platformă nu trebuie să trimită antetul X-Numora-Client. Trimiterea acestuia returnează 403 — acel antet este rezervat canalului desktop.

3. Chei Numora Studio (tnsr_)¶

Cheile Numora Studio autentifică aplicația desktop Numora Studio (macOS/Windows) folosită de practicieni pentru a genera rapoarte pentru clienți. Sunt asemănătoare cheilor de platformă, cu un format identic, dar sunt facturate împotriva alocației planului Numora Studio al organizației, nu a creditelor de platformă.

Furnizare¶

O cheie tnsr_ este creată fie:

• prin fluxul de autentificare al aplicației desktop (pagina de consimțământ din browser furnizează automat o cheie), sau
• manual, pe pagina Chei API din dashboard (/api-keys).

Semnătura canalului (obligatorie)¶

Fiecare apel efectuat cu o cheie tnsr_ trebuie să includă antetul canalului desktop:

Aplicare pe server:

• cheie tnsr_ fără X-Numora-Client → 403.
• cheie tnea_ cu X-Numora-Client → 403.

Contorizare¶

• Apelurile /api/v1 facturabile deduc din alocația planului Numora Studio a organizației (un singur fond comun pentru toate cheile tnsr_ ale organizației).
• Există o comutare de fallback la credite per cheie tnsr_: când alocația planului este epuizată, cheia poate recurge la creditele de platformă ale organizației (dezactivată implicit).
• Dacă alocația este epuizată și niciun fallback nu este activat, apelurile returnează 429.

Blocarea dispozitivelor (opțional)¶

O cheie tnsr_ poate fi blocată pe dispozitive înregistrate. Cu blocarea activată, fiecare solicitare trebuie să includă un X-Numora-Device-Id înregistrat în organizație; dispozitivele neînregistrate sunt respinse cu 403.

Endpoint-uri exclusive desktop¶

Unele endpoint-uri sunt rezervate canalului desktop și returnează 403 pentru cheile tnea_:

• POST /api/v1/numora/report-bundle — raport complet al clientului într-un singur apel
• POST /api/v1/numora/order — flux de achiziție în aplicație a planului/alocației
• POST /api/v1/numora/devices/register — înregistrarea unei instalări desktop
• GET /api/v1/numora/studio-status — solduri desktop și contoare de cotă

Sfat: răspunsurile facturabile includ, de asemenea, anteturile X-Remaining-Credits și X-Remaining-Tokens, astfel încât să puteți urmări soldurile în timp real fără apeluri suplimentare.

4. Gestionarea cheilor (Dashboard)¶

Pagina Chei API din dashboard (/api-keys) este centrul de control pentru ambele tipuri de chei.

Roluri: rolurile admin și developer pot crea și gestiona chei. finance nu poate crea chei API de producție. Operațiunile financiare (achiziții de planuri, încărcări de sold) sunt limitate la admin și finance.

Chei multiple: organizațiile pot deține multe chei de ambele tipuri — de exemplu o cheie tnsr_ per practician sau per instalare desktop. Alocațiile sunt partajate per organizație, deci cheile nu „concurează" niciodată pentru propriul sold.

5. Cele mai bune practici¶

• Tratați cheile ca pe parole. Nu le încorporați niciodată în cod client-side, depozite publice sau jurnale.
• Folosiți variabile de mediu sau un manager de secrete în backend-ul dvs.
• Rotiți imediat dacă o cheie este compromisă sau un membru al echipei pleacă.
• Folosiți o cheie tnsr_ per instalare desktop pentru a simplifica gestionarea dispozitivelor și revocarea.
• Activați blocarea dispozitivelor pentru organizațiile cu securitate ridicată.
• Monitorizați utilizarea în dashboard pentru a detecta devreme vârfuri neașteptate.

6. Întrebări frecvente¶

Poate o cheie tnsr_ să apeleze endpoint-uri obișnuite de platformă? Da. Cheile Numora Studio autentifică întreaga suprafață /api/v1; acele apeluri sunt facturate împotriva alocației planului Numora Studio.

Poate o cheie tnea_ să apeleze endpoint-urile /numora/* exclusive desktop? Nu. Endpoint-urile exclusive desktop returnează 403 pentru cheile de platformă.

De ce primesc 403 când apelez cu cheia mea tnsr_? Cel mai probabil antetul X-Numora-Client lipsește sau id-ul aplicației nu se potrivește. Verificați că fiecare solicitare include X-Numora-Client: numora-studio/<version>.

De ce primesc 403 cu cheia mea tnea_? Cheile de platformă nu trebuie să includă antetul X-Numora-Client — eliminați-l.

Ce se întâmplă când alocația mea se epuizează? Apelurile facturabile returnează 429 cu excepția cazului în care fallback-ul la credite este activat pe cheia dvs. tnsr_ (sau încărcați portofelul de platformă pentru cheile tnea_).

Conexe¶

• Primii pași
• Prețuri
• Soluții pentru întreprinderi