Autenticazione e idempotenza

Invia Authorization: Bearer <credential> con ogni richiesta, eccetto GET /pricing, GET /openapi.json e GET /openapi.yaml. Le credenziali nei parametri di query o in altre intestazioni vengono ignorate.

Le credenziali usano autenticazione Bearer; le credenziali vincolate a DPoP non sono supportate.

• Le chiavi API iniziano con sk_live_. Creale in Impostazioni → Sviluppatore; la chiave viene mostrata una sola volta. Conservala su un server e non distribuirla mai in un’applicazione per browser o mobile. Ti inviamo un’e-mail 7 giorni prima della scadenza.
• I token di accesso OAuth iniziano con sf_at_. I client MCP li ricevono dopo la tua autorizzazione; puoi scollegare un client in Impostazioni → Sviluppatore → Applicazioni collegate.
• Credenziali mancanti, non valide, scadute o revocate restituiscono 401 UNAUTHORIZED. Un account che non può usare l’API, ad esempio perché è in fase di eliminazione, restituisce 401 ACCOUNT_UNAVAILABLE.
• La revoca di una chiave impedisce nuove richieste con quella chiave; i processi già creati continuano e restano consultabili con altre credenziali dello stesso account.

Una richiesta fuori dall’ambito delle credenziali restituisce 403 SCOPE_DENIED. Usa una chiave diversa per ogni applicazione e ambiente, così puoi revocarne una senza influire sulle altre.

• Ogni richiesta di creazione (POST /images/*, /charts/*, /flowcharts/*) richiede un’intestazione Idempotency-Key con 1–255 caratteri ASCII visibili. Un UUID casuale per richiesta è la scelta più semplice. Anche i caricamenti su POST /files possono inviarla; consulta file.
• La stessa chiave con lo stesso corpo restituisce lo stesso processo e non riserva altri crediti. Per i caricamenti dei grafici, i byte del file di dati fanno parte del corpo.
• La stessa chiave con un corpo diverso restituisce 409 IDEMPOTENCY_CONFLICT. Richieste simultanee con la stessa chiave non creano mai due processi: ciascuna restituisce lo stesso processo oppure 409 IDEMPOTENCY_IN_PROGRESS con Retry-After: 1 mentre la prima viene ancora ammessa.
• Riprova con la stessa chiave dopo un timeout, un errore di rete, un 429 o un 503: è l’unico modo per garantire che un processo non venga creato due volte.
• Una volta creato il processo, un errore che consente un nuovo tentativo (429, 503, 409 IDEMPOTENCY_IN_PROGRESS) o 500 INTERNAL_ERROR include details.job_id. Riprova con la stessa chiave o consulta GET /jobs/{job_id}; non passare a una nuova chiave, che creerebbe e addebiterebbe un secondo processo. Un processo accettato ma non rileggibile riceve una risposta 202 con stato queued.
• Una richiesta rifiutata, ad esempio 402 INSUFFICIENT_CREDITS, conserva quella risposta per la sua chiave. Dopo una ricarica o il passaggio a un piano superiore, inviala di nuovo con una nuova chiave.

• I client MCP usano OAuth 2.1 con PKCE. I token di accesso (sf_at_…) sono validi per 1 ora. Un client che richiede l’ambito offline_access riceve anche un token di rinnovo (sf_rt_…) valido per 30 giorni e rimane collegato finché non lo scolleghi; senza offline_access, devi accedere di nuovo quando scade il token di accesso.
• I token di rinnovo ruotano: ogni rinnovo ne restituisce uno nuovo. Presentare un token già usato viene considerato riutilizzo e revoca i token emessi a partire da esso, quindi il client deve accedere nuovamente.
• La registrazione dinamica dei client accetta un corpo di massimo 16 KB, con limiti alla lunghezza di ogni campo e al numero di URI di reindirizzamento. L’autenticazione dell’endpoint dei token è none per i client pubblici con PKCE oppure client_secret_basic.
• Un client registrato ma mai autorizzato viene eliminato dopo 24 ore.
• Una richiesta di autorizzazione con prompt=login o max_age richiede un nuovo accesso. Se hai già effettuato l’accesso, SciFig chiede conferma prima di disconnetterti e farti accedere nuovamente.
• I limiti delle credenziali OAuth vengono conteggiati per client e account: gli altri utenti dello stesso assistente non consumano i tuoi limiti.

Ogni risposta include X-Request-Id; i corpi degli errori lo ripetono come error.request_id. Identifica la richiesta nei nostri registri senza esporre altre informazioni, quindi puoi registrarlo e fornirlo quando contatti l’assistenza.