Autenticazione

Ogni richiesta all’API porta una chiave API nell’header Authorization:

Authorization: Bearer sk-popnow-3f9c0a…

Non esistono altri modi per autenticarsi: le chiavi nella query string dell’URL non vengono mai accettate, e il tuo accesso a popnow.ai non vale per l’API.

Un’eccezione: le route compatibili con OpenAI sotto /v1 leggono la chiave anche dall’header x-api-key, così i client in stile OpenAI funzionano senza modifiche. Le route native /api/v1 leggono solo Authorization.

Com’è fatta una chiave

Una chiave è sk-popnow- seguito da 48 caratteri esadecimali minuscoli. Dopo la creazione la console API ne mostra solo i primi caratteri, quindi una chiave persa non si può recuperare: creane una nuova.

Crea una chiave

1. Accedi a popnow.ai e apri la console API.
2. Scegli Create key e dalle un nome che dica dove verrà usata, per esempio production-backend.
3. Copiala subito. Viene mostrata una volta sola.

Puoi avere più chiavi contemporaneamente. Una per ambiente o per servizio è una buona abitudine, perché puoi revocarne una senza toccare le altre. Tutte attingono allo stesso saldo di crediti.

Dove conservarla

• In una variabile d’ambiente o nel gestore di segreti della tua piattaforma (POPNOW_API_KEY), non nel codice sorgente.
• Mai in un browser, in un’app mobile o in qualsiasi codice che giri sul dispositivo di qualcun altro. Chi può leggere la chiave può spendere i tuoi crediti. Metti in mezzo il tuo server e lascia che sia lui a chiamare PopNow.
• Nemmeno nei log. Se registri gli header delle richieste, togli prima Authorization.

Limita cosa può fare una chiave

Ogni chiave può avere i propri limiti, impostati nella console API:

Di default una chiave non ha restrizioni né tetti. Alle chiavi di produzione dai il perimetro più stretto che funziona.

Le attività appartengono alla chiave che le ha create

recordInfo, retry, purge, l’elenco delle attività e l’utilizzo vedono solo le attività create con la stessa chiave. Un’attività creata con un’altra chiave del tuo account risponde 404, esattamente come un’attività inesistente. Anche le generazioni avviate dal sito non sono visibili a nessuna chiave. Per una visione dell’intero account usa la console API.

Rotazione

Per sostituire una chiave senza interruzioni:

1. Crea la nuova chiave.
2. Distribuiscila ovunque si usava quella vecchia.
3. Controlla nella console che l’ultimo utilizzo della vecchia chiave smetta di cambiare.
4. Revoca la vecchia chiave.

Se una chiave trapela

1. Revocala subito dalla console API. Ha effetto dalla richiesta successiva.
2. Creane una sostitutiva e distribuiscila.
3. Controlla per cosa è stata usata: log e utilizzo nella console mostrano ogni attività creata da quella chiave.
4. Restringi la sostitutiva con una lista di IP consentiti e un tetto di spesa.

Se vedi spese che non hai fatto tu, contatta l’assistenza.

Com’è fatto un errore

I tre problemi di autenticazione restituiscono HTTP 401 con code: 401; a distinguerli è msg:

Anche una chiave valida può ricevere 403, per esempio se l’indirizzo email dell’account non è ancora verificato (40310). Vedi Errori.