Autenticazione e accesso

Le API pubbliche usano tre meccanismi diversi, a seconda della superficie.

API key

Ogni agenzia può avere una API key. Si invia come token Bearer:

GET /cus/property HTTP/1.1
Host: api.namai.it
Authorization: Bearer <API_KEY>

La chiave identifica l'agenzia: i dati restituiti sono sempre e solo quelli di quell'agenzia. Non esistono permessi più fini: chi ha la chiave legge tutti i feed.

Questi due messaggi non portano un codice a sei cifre.

Come si ottiene una chiave

Non esiste ancora un'interfaccia per generarla o ruotarla. La chiave viene assegnata dal team namai su richiesta dell'agenzia. Se sospetti che sia stata esposta, chiedi la sostituzione.

Trattala come una password: non inserirla in codice che gira nel browser o in app distribuite agli utenti, e usala solo da un server.

Tracciamento

Ogni chiamata a un feed con API key viene registrata nel Registro sicurezza dell'agenzia come accesso API. L'amministratore dell'agenzia può quindi vedere quando e quante volte il feed è stato letto.

Sito vetrina: l'host identifica l'agenzia

Le rotte /site/* non vogliono credenziali. L'agenzia si ricava dall'header Host:

1. se l'host coincide con un dominio registrato per l'agenzia, vale quello;
2. altrimenti, se è del tipo <sottodominio>.namai.it (anche con www.), vale il sottodominio.

Il sito deve essere pubblicato e l'agenzia attiva. Altrimenti la risposta è:

HTTP/1.1 404 Not Found
Cache-Control: no-store

{ "error": "000000:sito non trovato" }

L'host è letto dall'header Host e non da X-Forwarded-Host. Se chiami namai dal tuo server (rendering lato server o proxy), inoltra l'Host del sito dell'agenzia, non il tuo.

Solo le scritture sono protette da anti-spam: vedi sito-vetrina.md.

Link di condivisione

Il token è un JWT firmato che fa parte dell'URL (/v1/share/<token>/…). Chi lo possiede legge quel solo documento, per il tempo di validità del link (30 giorni per impostazione predefinita; è una scelta di chi gestisce l'installazione di namai, non della singola agenzia). Un token errato o scaduto dà 404 con Link non valido o scaduto. Dettagli in link-condivisione.md.

CORS

Le rotte /site/* sono pensate per essere chiamate dalla stessa origine del sito: non servono intestazioni CORS. Dal browser su un'altra origine la chiamata sarà bloccata; per un front-end separato usa un proxy lato server che inoltri l'Host corretto. Le origini consentite con credenziali sono limitate a quelle dell'app e del sito di presentazione di namai.