Chiavi API — tnea_ e tnsr_¶

NumerologyAPI utilizza due famiglie di chiavi API. Entrambe hanno un aspetto simile, vengono generate con lo stesso formato sicuro di 80 caratteri e si autenticano con lo stesso header X-API-Key — ma sono contabilizzate in modo diverso e sono destinate a prodotti diversi.

1. Formato e Sicurezza delle Chiavi¶

Ogni chiave è lunga esattamente 80 caratteri:

tnea_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
tnsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Il prefisso di 4 caratteri identifica il tipo di chiave; i restanti 75 caratteri sono generati con una sorgente casuale crittograficamente sicura.
• Le chiavi vengono salvate sul server con hash SHA-256. La chiave in chiaro viene mostrata una sola volta, al momento della creazione.
• Se una chiave viene mai esposta, ruotala immediatamente dal pannello di controllo.

2. Chiavi Piattaforma (tnea_)¶

Le chiavi piattaforma sono le chiavi standard per integrare NumerologyAPI nel tuo prodotto — siti web, app mobile e servizi lato server.

Autenticazione¶

Invia la chiave in ogni richiesta con l'header 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"

Contabilizzazione¶

Le chiamate fatturabili /api/v1 vengono addebitate sul portafoglio di crediti dell'organizzazione (pay-as-you-go). Puoi ricaricare il portafoglio in qualsiasi momento dal pannello di controllo.

Regola del canale: le chiavi piattaforma non devono inviare l'header X-Numora-Client. L'invio restituisce 403 — quell'header è riservato al canale desktop.

3. Chiavi Numora Studio (tnsr_)¶

Le chiavi Numora Studio autenticano l'app desktop Numora Studio (macOS/Windows) utilizzata dai professionisti per generare rapporti per i clienti. Sono una variante delle chiavi piattaforma con formato identico, ma vengono fatturate sulla quota del piano Numora Studio dell'organizzazione anziché sui crediti piattaforma.

Provisioning¶

Una chiave tnsr_ viene creata in uno di questi due modi:

• tramite il flusso di accesso dell'app desktop (la pagina di consenso del browser crea la chiave automaticamente), oppure
• manualmente sul pannello di controllo nella pagina Chiavi API (/api-keys).

Firma del canale (obbligatoria)¶

Ogni chiamata effettuata con una chiave tnsr_ deve includere l'header del canale desktop:

Applicazione lato server:

• chiave tnsr_ senza X-Numora-Client → 403.
• chiave tnea_ con X-Numora-Client → 403.

Contabilizzazione¶

• Le chiamate fatturabili /api/v1 vengono addebitate sulla quota del piano Numora Studio dell'organizzazione (un pool condiviso tra tutte le chiavi tnsr_ dell'organizzazione).
• Esiste un'opzione di fallback sui crediti per ogni chiave tnsr_: quando la quota del piano è esaurita, la chiave può ripiegare sui crediti piattaforma dell'organizzazione (disattivata per impostazione predefinita).
• Se la quota è esaurita e nessun fallback è attivo, le chiamate restituiscono 429.

Blocco del dispositivo (opzionale)¶

Una chiave tnsr_ può essere bloccata su dispositivi registrati. Con il blocco attivato, ogni richiesta deve includere un X-Numora-Device-Id registrato presso l'organizzazione; i dispositivi non registrati vengono rifiutati con 403.

Endpoint esclusivi per il desktop¶

Alcuni endpoint sono riservati al canale desktop e restituiscono 403 per le chiavi tnea_:

• POST /api/v1/numora/report-bundle — rapporto completo del cliente in una sola chiamata
• POST /api/v1/numora/order — flusso di acquisto del piano/quota in-app
• POST /api/v1/numora/devices/register — registra un'installazione desktop
• GET /api/v1/numora/studio-status — saldi desktop e contatori quota

Suggerimento: le risposte fatturabili includono anche gli header X-Remaining-Credits e X-Remaining-Tokens per monitorare i saldi in tempo reale senza chiamate aggiuntive.

4. Gestione delle Chiavi (Pannello di Controllo)¶

La pagina Chiavi API del pannello di controllo (/api-keys) è il centro di gestione per entrambi i tipi di chiave.

Ruoli: i ruoli admin e developer possono creare e gestire le chiavi. finance non può creare chiavi API di produzione. Le operazioni finanziarie (acquisti di piani, ricariche) sono limitate a admin e finance.

Chiavi multiple: le organizzazioni possono detenere molte chiavi di entrambi i tipi — ad esempio una chiave tnsr_ per ogni professionista o per ogni installazione desktop. Le quote sono condivise per organizzazione, quindi le chiavi non "competono" mai per il proprio saldo.

5. Buone Pratiche¶

• Tratta le chiavi come password. Non incorporarle mai nel codice lato client, nei repository pubblici o nei log.
• Utilizza variabili d'ambiente o un gestore di segreti nel tuo backend.
• Ruota immediatamente se una chiave viene compromessa o se un membro del team lascia l'organizzazione.
• Usa una chiave tnsr_ per ogni installazione desktop per semplificare la gestione dei dispositivi e la revoca.
• Attiva il blocco del dispositivo per le organizzazioni ad alta sicurezza.
• Monitora l'utilizzo nel pannello di controllo per individuare tempestivamente picchi inaspettati.

6. Domande Frequenti¶

Una chiave tnsr_ può chiamare i normali endpoint piattaforma? Sì. Le chiavi Numora Studio autenticano l'intera superficie /api/v1; quelle chiamate vengono fatturate sulla quota del piano Numora Studio.

Una chiave tnea_ può chiamare gli endpoint /numora/* esclusivi per il desktop? No. Gli endpoint esclusivi per il desktop restituiscono 403 per le chiavi piattaforma.

Perché ricevo 403 quando chiamo con la mia chiave tnsr_? Molto probabilmente manca l'header X-Numora-Client oppure l'id dell'app non corrisponde. Verifica che ogni richiesta includa X-Numora-Client: numora-studio/<version>.

Perché ricevo 403 con la mia chiave tnea_? Le chiavi piattaforma non devono trasportare l'header X-Numora-Client — rimuovilo.

Cosa succede quando la mia quota si esaurisce? Le chiamate fatturabili restituiscono 429 a meno che il fallback sui crediti non sia attivo sulla tua chiave tnsr_ (oppure ricarichi il portafoglio piattaforma per le chiavi tnea_).

Correlati¶

• Per Iniziare
• Prezzi
• Soluzioni Enterprise