IntelligenceBox

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

    Apri le impostazioni API key

    In IntelligenceBox vai su Impostazioni → Sistema → API key.
  2. 2

    Dalle il nome di chi la userà

    Un’etichetta come zapier-fatture o ci-notifiche rende ovvio, mesi dopo, quale chiave revocare.
  3. 3

    Copia la chiave

    Inizia con key- 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.

HTTP
x-api-key: YOUR_API_KEY

# oppure, se il tuo client preferisce l’auth standard:
Authorization: Bearer YOUR_API_KEY
curl 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:

JSON
{
  "error": "Request body validation failed",
  "code": "VALIDATION_ERROR",
  "details": [
    { "path": "title", "message": "Expected string, received number" }
  ]
}
  • 400VALIDATION_ERROR — corpo o query non validi. details elenca 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 rispondono 404 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”.

Shell
curl BOX_URL/health
# {"status":"ok"}

Prosegui con tutto quello che puoi fare con il box.

Autenticazione | IntelligenceBox