Autenticazione

Le applicazioni chiamano l'API di Prynt con una chiave API del workspace. Le persone usano la web app con il proprio account e la propria sessione; le chiavi sono per i server: il tuo ERP, il WMS, il backend e-commerce o i job batch.

Chiavi API del workspace#

Una chiave appartiene a un solo workspace e può generare soltanto i template di quel workspace con le sue sorgenti dati. Ogni chiave ha un nome, una modalità (live o test), un insieme di scope, un ambiente predefinito e una data di scadenza facoltativa.

• La chiave completa ha la forma prynt_live_k3x9a2mq_…: un prefisso visibile (prynt_live_k3x9a2mq) che identifica la chiave negli elenchi e nei log, seguito dal segreto.
• Il segreto viene mostrato una sola volta, alla creazione della chiave. Prynt ne conserva solo un hash e non può mostrarlo di nuovo.
• Ogni generazione registra la chiave che l'ha richiesta: la pagina Log mostra nome e prefisso della chiave accanto a ogni esecuzione.

Chiavi live e test#

Le chiavi iniziano con prynt_live_ o prynt_test_. Le chiavi live sono per i sistemi di produzione e possono usare tutti gli ambienti. Le chiavi di test sono per development, staging e test automatici: una richiesta con una chiave di test verso un ambiente di produzione fallisce con 403 ENVIRONMENT_NOT_ALLOWED, così un sistema di test non può mai leggere per errore i dati di produzione. I prefissi rendono inoltre facile riconoscere una chiave trapelata, per te e per i secret scanner.

L'ambiente predefinito della chiave viene usato quando una richiesta non ne indica uno (environment nella richiesta di generazione). Per le chiavi live il predefinito è production, per quelle di test development.

Scope#

Gli scope limitano ciò che una chiave può fare. Concedi solo quello che serve all'applicazione: alla maggior parte delle integrazioni basta render.

Inviare la chiave#

Invia la chiave nell'header Authorization come bearer token, su HTTPS. L'API si trova sotto /api/v1 di https://api.prynt.it.

curl https://api.prynt.it/api/v1/templates \  -H "Authorization: Bearer prynt_live_..." \  -H "Prynt-Workspace: 0199b8a1-…"

L'header Prynt-Workspace

La chiave identifica già il proprio workspace, quindi l'header Prynt-Workspace è facoltativo. Se lo invii (l'id del workspace mostrato nell'API explorer), Prynt verifica che la chiave appartenga a quel workspace e in caso contrario risponde 403 WORKSPACE_MISMATCH: una protezione semplice contro la chiave di un altro workspace finita in un file di configurazione.

Creare e revocare le chiavi#

• Nella web app, apri Sviluppatori → Chiavi API (permesso apikeys.manage: owner, admin e sviluppatori) e scegli Crea chiave API. Scegli la modalità, gli scope, l'ambiente predefinito e una scadenza (mai, 30, 90 o 365 giorni, oppure una data).
• Copia la chiave dalla finestra di dialogo: non verrà più mostrata.
• Revoca una chiave dalla stessa pagina. La revoca è immediata: la richiesta successiva con quella chiave fallisce con 401 API_KEY_REVOKED.
• Per ruotare una chiave senza interruzioni, crea una nuova chiave, distribuiscila nella tua applicazione, verifica nella pagina Log che le richieste la usino, poi revoca la vecchia.

Limiti di frequenza#

Per impostazione predefinita ogni chiave può inviare fino a 600 richieste al minuto. Oltre questo limite l'API risponde 429 Too Many Requests con errorCode RATE_LIMITED e un header Retry-After con i secondi da attendere. Riprova dopo quel tempo, con backoff esponenziale e un po' di jitter; per grandi volumi preferisci la generazione asincrona (async: true).

HTTP/1.1 429 Too Many RequestsRetry-After: 12Content-Type: application/problem+json {  "title": "Too many requests",  "status": 429,  "errorCode": "RATE_LIMITED",  "correlationId": "4bf92f3577b34da6a3ce929d0e0e4736"}

Errori di autenticazione#

Come tutti gli errori dell'API, gli errori di autenticazione sono problem details RFC 9457 con un errorCode stabile e il correlationId della richiesta.