Autenticazione

Credenziali PMS: formato, ambienti, conservazione, rotazione e revoca.

Ogni richiesta, tranne GET /v1/health, porta la tua credenziale PMS come token Bearer:

GET /v1/me HTTP/1.1
Host: staging.api.tatallo.com
Authorization: Bearer tat_stg_sk_<credential-id>_<secret>

Non c’è uno scambio di token e non c’è nulla da rinnovare: la chiave stessa è la credenziale. Una chiave può avere una data di scadenza, che Tatallo ti comunica quando la emette.

​

Formato della chiave e ambienti

Una credenziale PMS è una stringa opaca emessa da Tatallo. Il prefisso indica l’ambiente a cui appartiene:

Prefisso	Ambiente	Base URL
tat_stg_sk_	Staging	https://staging.api.tatallo.com
tat_live_sk_	Produzione	https://api.tatallo.com

Una chiave funziona solo nel proprio ambiente. Una chiave di staging inviata alla produzione riceve 401, e lo stesso accade a una chiave di produzione inviata allo staging: il traffico di prova non può mai raggiungere i dati reali. Considera opaco il resto della chiave: non analizzarlo.

​

Tieni le chiavi sui tuoi server

• Chiama l’API PMS Tatallo solo da server a server. Non consegnare mai una chiave a un browser, a un’app mobile o a qualsiasi altro client.
• Conserva le chiavi nel gestore dei segreti, non nel codice sorgente né nei file di configurazione.
• Non registrare mai una chiave nei log, e non registrare l’header Authorization. GET /v1/me non restituisce mai un segreto, quindi registrarne la risposta è sicuro.
• Se una chiave può essere trapelata, avvisa subito [e-mail]. Tatallo la revoca immediatamente.

​

Rotazione e revoca

Chiedi a [e-mail] di ruotare una chiave. Tatallo emette prima la chiave nuova, tramite un link segreto monouso. Passi i tuoi server alla chiave nuova, e Tatallo revoca quella vecchia solo quando vede chiamate fatte con la nuova: così il servizio non si interrompe.

Una chiave revocata o scaduta riceve 401 dalla richiesta successiva.

​

401 o 403?

Stato	Codice	Che cosa significa	Che cosa fare
401	unauthorized	La chiave manca, è malformata, appartiene all’altro ambiente, è scaduta oppure è stata revocata. Tutti questi casi ricevono la stessa risposta, di proposito.	Controlla l’header, il prefisso rispetto alla base URL e che la chiave sia quella attuale.
403	insufficient_scope	La chiave è valida, ma non ha lo scope richiesto dalla route (properties:read per le proprietà).	Chiedi una chiave con quello scope.

GET /v1/me mostra gli scope della chiave che stai usando.