> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# API pubblica, chiavi e webhook

La superficie REST versionata su cui i tuoi clienti costruiscono.

## Prima di iniziare

Apri il progetto supastack scaricato in Visual Studio Code utilizzando File → Apri cartella, quindi scegli Terminale → Nuovo terminale. La radice del repository è la cartella contenente package.json, app e pacchetti. Esegui il comando qui sotto e lascia il suo terminale aperto. Se un comando non viene riconosciuto, completare la guida all'installazione dello strumento prima di continuare.

Leggi prima il tutorial sulla piattaforma. Un server è il processo dell'app che risponde alle richieste del browser o del telefono. Il Web legge apps/web/.env.local, Expo legge apps/mobile/.env.local e i comandi di migrazione del database leggono root .env. La dimostrazione senza database/dashboard è separata dagli account reali/auth, che necessitano della migrazione Postgres. Un pagamento solo telefonico o desktop richiede un backend Web eseguito separatamente.

[Installa gli strumenti e ottieni il codice](https://supastack.dev/it/docs/web/before-you-start.md)

[Impara comandi, file e configurazione](https://supastack.dev/it/docs/web/terminal-basics.md)

[Completa il tutorial di prima esecuzione sul Web](https://supastack.dev/it/docs/web/ship-in-5-minutes.md)

```
corepack pnpm --filter @supastack/web dev
```


## Installazione e configurazione

packages/api definisce il contratto versionato: schemi zod per ogni richiesta e risposta, l'involucro di errore e il documento OpenAPI servito su /api/v1/openapi e renderizzato su /api/docs. Le chiavi API del workspace si creano in Impostazioni → Sviluppatori; il testo in chiaro si mostra una volta, poi persiste solo la chiave con hash.

Le chiavi sono prefissate (sk_<env>_…), con scope (read di default) e risolte a un workspace a ogni richiesta. Le sottoscrizioni webhook in uscita si gestiscono dalla stessa superficie Sviluppatori.

```
GET  /api/v1/workspaces/current
GET  /api/v1/entitlements
GET  /api/v1/models/requirements
POST /api/v1/ai-tasks
GET  /api/v1/openapi           # machine-readable spec
GET  /api/docs                 # rendered reference

Authorization: Bearer sk_live_…
```


## Flusso di implementazione

Autenticati con la chiave Bearer; il server risolve il workspace dalla chiave, mai da un id fornito dal client. Mantieni le forme di risposta versionate — cambiamenti additivi dentro v1, cambiamenti breaking dietro una nuova versione.

Per i webhook in uscita, sottoscrivi un URL endpoint al catalogo eventi; le consegne sono firmate e registrate così i consumatori possono verificare e riprodurre. Usa webhook-events.ts per il catalogo e webhook-delivery.ts per i tentativi.


## Verifica e risoluzione dei problemi

Verifica che una chiave revocata restituisca 401, che una chiave con scope insufficiente sia negata e che il documento OpenAPI si parsi. Per i webhook, testa la verifica della firma, la riconsegna dopo fallimento e che i payload degli eventi non portino mai secret del provider.


## Successivo

[Archiviazione file](https://supastack.dev/it/docs/web/storage.md)