Per iniziare
Autenticazione
Tutti gli endpoint tranne il controllo di salute richiedono una API key. Le chiavi si creano nell’app desktop e appartengono a chi le ha create: una chiamata fatta con la tua chiave può fare esattamente quello che puoi fare tu, niente di più.
Creare una chiave#
- 1
Apri le impostazioni API key
In IntelligenceBox vai su Impostazioni → Sistema → API key. - 2
Dalle il nome di chi la userà
Un’etichetta comezapier-fattureoci-notificherende ovvio, mesi dopo, quale chiave revocare. - 3
Copia la chiave
Inizia conkey-e viene mostrata una volta sola. Conservala nel tuo gestore di segreti, non nel codice sorgente.
Tratta la chiave come una password
Una chiave porta con sé tutti gli accessi di chi l’ha creata: le sue cartelle, i suoi assistenti, le sue conversazioni. Chiunque la possieda può leggerli. Revocala appena sospetti che sia uscita — dalla stessa schermata delle impostazioni si elencano e si eliminano.Inviare la chiave#
Vanno bene entrambi gli header. Scegline uno e usalo sempre.
x-api-key: YOUR_API_KEY
# oppure, se il tuo client preferisce l’auth standard:
Authorization: Bearer YOUR_API_KEYcurl BOX_URL/api/public/me \
-H "x-api-key: YOUR_API_KEY"GET /api/public/me è il modo più economico per verificare una chiave: restituisce l’identità a cui appartiene, il workspace su cui è finita la richiesta e qualche conteggio. Usalo come controllo di connettività prima di fare lavoro vero.
Scoping del workspace#
Header opzionali che decidono in quale workspace la richiesta legge e scrive.
x-organization-idstring- Il workspace aziendale a cui appartiene la richiesta. Se lo ometti, la chiamata resta nel workspace personale di chi possiede la chiave.
x-organization-scopePERSONAL | ORGANIZATION | LEGACY- Come vengono assegnate le risorse create da questa richiesta. Ignorato se non è presente anche
x-organization-id.Predefinito:PERSONAL.
Il default è prudente
Senza questi header tutto ciò che crei — cartelle, assistenti, notifiche — finisce nel workspace personale di chi possiede la chiave. È voluto: un header di troppo non deve poter pubblicare risorse in un’azienda a cui la chiave non è stata autorizzata.Risposte di errore#
Ogni errore usa la stessa struttura, così puoi ramificare su code invece di interpretare il testo:
{
"error": "Request body validation failed",
"code": "VALIDATION_ERROR",
"details": [
{ "path": "title", "message": "Expected string, received number" }
]
}400VALIDATION_ERROR— corpo o query non validi.detailselenca i campi che non tornano.401UNAUTHORIZED— chiave assente, malformata o revocata.403FORBIDDEN— la chiave è valida ma chi la possiede non può toccare questa risorsa.404NOT_FOUND— la risorsa non esiste, oppure non ti è consentito sapere che esiste.409CONFLICT— una regola di unicità ha rifiutato la scrittura, ad esempio un handle di assistente già in uso.500INTERNAL_ERROR— qualcosa è fallito sul box. Si può ritentare con backoff.
A volte il 404 è un 403 travestito
Gli endpoint che modificano una risorsa rispondono404 quando chi chiama la vede ma non la possiede. È voluto: un assistente condiviso col team non deve confermare la propria esistenza a una chiave che non può modificarlo.L’unico endpoint senza autenticazione#
GET /health non vuole chiavi. Usalo per il monitoraggio e per distinguere “box irraggiungibile” da “credenziali sbagliate”.
curl BOX_URL/health
# {"status":"ok"}Prosegui con tutto quello che puoi fare con il box.