# Autenticazione e idempotenza

Credenziali, ambiti, Idempotency-Key e identificativi delle richieste per ogni chiamata all’API SciFig.

Fonte: https://scifig.ai/it/docs/api/authentication

## Autenticazione Bearer

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.

## Ambiti

| Ambito | Autorizzazioni | Tipo di chiave API |
| --- | --- | --- |
| figures:read | `GET /jobs`, `GET /jobs/{id}`, `GET /files/{file_id}`, `GET /credits` | Chiave di sola lettura; può non scadere mai |
| figures:generate | Tutto ciò che include `figures:read`, più ogni endpoint `POST` | Chiave di generazione; scade dopo 30 giorni, 90 giorni o 1 anno; richiede un abbonamento attivo o un saldo positivo di crediti acquistati in pacchetti |

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.

## Idempotenza

- 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](/it/docs/api/files#upload).
- 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.

## Client OAuth

- 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.

## Identificativi delle richieste

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.