Autenticazione

AstroAPI supporta più metodi di autenticazione in base al caso d'uso.

Autenticazione tramite Chiave API

Le chiavi API sono il metodo consigliato per la comunicazione server-to-server.

Ottenere una Chiave API

1. Accedi alla Dashboard di AstroAPI
2. Vai su Impostazioni > Chiavi API
3. Clicca su Crea Chiave API
4. Configura i permessi e i limiti di utilizzo
5. Copia la chiave generata (non verrà mostrata di nuovo)

Utilizzo delle Chiavi API

Includi la tua chiave API nell'intestazione X-Api-Key:

curl -X GET "https://api.astroapi.cloud/api/calc/natal" \
  -H "X-Api-Key: ak_live_xxxxxxxxxxxx"

Permessi delle Chiavi API

Le chiavi API possono essere limitate a permessi specifici:

Permesso	Descrizione
calc:read	Accesso agli endpoint di calcolo
content:read	Accesso agli endpoint di contenuto/interpretazione
chart:read	Accesso agli endpoint di rendering dei temi
modules:read	Accesso ai moduli acquistati

Ruoli

AstroAPI utilizza il controllo degli accessi basato sui ruoli all'interno delle organizzazioni:

Ruolo	Descrizione
owner	Accesso completo a tutte le funzionalità dell'organizzazione
manager	Può gestire utenti, fatturazione e contenuti
member	Accesso di base ai calcoli e alla lettura dei contenuti

Permessi dei Ruoli

Permesso	owner	manager	member	Descrizione
org:create	✅			Crea organizzazione
org:read	✅	✅	✅	Legge l'organizzazione
org:update	✅	✅		Aggiorna l'organizzazione
org:users:read	✅	✅		Legge gli utenti
org:users:create	✅	✅		Invita utenti
org:users:update	✅	✅		Aggiorna gli utenti
org:users:delete	✅	✅		Rimuove gli utenti
billing:read	✅	✅		Visualizza la fatturazione
billing:manage	✅	✅		Gestisce la fatturazione
content:read	✅	✅	✅	Legge i contenuti
content:create	✅	✅		Crea contenuti
content:update	✅	✅		Aggiorna i contenuti
content:delete	✅	✅		Elimina i contenuti
content:custom-copy	✅	✅	✅	Crea copie personalizzate
content:restore	✅	✅		Ripristina i contenuti
calc:use	✅	✅	✅	Usa gli endpoint di calcolo
chart:use	✅	✅	✅	Usa gli endpoint dei temi
modules:read	✅	✅	✅	Legge le informazioni sui moduli
admin:access	✅			Accesso amministratore

Contesto dell'Organizzazione

Per le applicazioni multi-tenant, le chiavi API sono associate alle organizzazioni. Il contesto dell'organizzazione viene applicato automaticamente in base alla chiave API utilizzata.

Restrizioni di Dominio

Le chiavi API possono essere configurate con restrizioni di dominio per limitare i siti web che possono utilizzarle:

• example.com - Corrispondenza esatta del dominio
• *.example.com - Tutti i sottodomini
• * - Consenti tutti i domini (non consigliato)

Configura le restrizioni di dominio nella dashboard durante la creazione o la modifica di una chiave API.

Limitazione Importante

Le restrizioni di dominio proteggono solo dall'abuso tramite browser. Si basano sulle intestazioni Origin e Referer, che i browser rispettano ma che possono essere facilmente falsificate al di fuori del browser (ad esempio con curl, script o codice lato server).

Utilizzo Lato Client vs Lato Server

Server-to-Server (Consigliato)

Per le applicazioni in produzione, utilizza sempre le chiavi API sul tuo server backend:

┌─────────────┐      ┌─────────────────┐      ┌─────────────┐
│   Browser   │ ───► │  Your Backend   │ ───► │  AstroAPI   │
│  (no keys)  │      │  (API key here) │      │             │
└─────────────┘      └─────────────────┘      └─────────────┘

Questo approccio:

• Mantiene la tua chiave API sicura e nascosta
• Ti consente di aggiungere il tuo livello di autenticazione
• Impedisce agli utenti finali di estrarre la chiave API
• Abilita la firma delle richieste e misure di sicurezza aggiuntive

Utilizzo Lato Client / Browser

Se devi utilizzare le chiavi API direttamente nel browser (ad esempio widget incorporati su siti statici), tieni presente le limitazioni:

• Le chiavi API sono visibili nel codice sorgente JavaScript e nelle richieste di rete
• Chiunque può estrarre la chiave dal tuo sito web
• Le restrizioni di dominio impediscono solo ad altri siti di utilizzare la tua chiave via JavaScript — non impediscono a qualcuno di copiare la chiave e usarla altrove

Per l'utilizzo lato client, ti consigliamo di:

• Abilitare le restrizioni di dominio
• Impostare limiti di utilizzo severi
• Utilizzare tempi di scadenza brevi
• Monitorare l'utilizzo per rilevare anomalie

Responsabilità del Cliente

Importante

Sei responsabile della sicurezza e dell'utilizzo delle tue chiavi API.

Tutte le richieste API effettuate con la tua chiave API vengono conteggiate nel tuo quota e addebitate al tuo account, indipendentemente dal fatto che siano state effettuate da te o da qualcuno che ha ottenuto la tua chiave.

Se esponi una chiave API nel codice lato client e viene utilizzata in modo improprio, sei responsabile dell'utilizzo e dei costi risultanti. AstroAPI non è in grado di distinguere tra richieste legittime e richieste non autorizzate effettuate con una chiave API valida.

Per ridurre al minimo il rischio:

1. Utilizza la comunicazione server-to-server quando possibile
2. Non includere mai le chiavi API nel controllo di versione
3. Ruota immediatamente le chiavi se sospetti che siano state compromesse
4. Configura avvisi di utilizzo per rilevare picchi imprevisti

Migliori Pratiche di Sicurezza

• Utilizza la comunicazione server-to-server per le applicazioni in produzione
• Non esporre mai le chiavi API nel codice lato client, a meno che non sia assolutamente necessario
• Ruota periodicamente le chiavi API
• Utilizza i permessi minimi richiesti
• Abilita le restrizioni di dominio per le chiavi lato client
• Imposta limiti di utilizzo appropriati
• Monitora l'utilizzo delle chiavi API nella dashboard