IntelligenceBox

Autenticazione

Gli endpoint della Box, 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ù.

Per inviare segnalazioni al servizio auth servono un JWT cloud o una chiave API cloud. Vedi la guida alle segnalazioni per indirizzo, credenziali e permessi.

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.

Scaricare i file#

Alcune risposte contengono indirizzi di file sul box: gli allegati di una conversazione, i documenti generati (/uploads/…), i file delle cartelle (/files/…). Anche quegli indirizzi vogliono la chiave: scaricali con lo stesso header delle altre chiamate.

Shell
curl -o Prospetto.xlsx BOX_URL/uploads/xlsx-generated/21440576_Prospetto.xlsx \
  -H "x-api-key: YOUR_API_KEY"

Dove non puoi impostare header — un <img>, un link aperto nel browser — aggiungi la chiave all’indirizzo come ?auth_token=YOUR_API_KEY. Un indirizzo con la chiave dentro finisce nella cronologia e nei log come qualsiasi URL: usalo solo dove non c’è alternativa, e mai in qualcosa che condividi.

html
<img src="BOX_URL/files/dataai/FOLDER_ID/.images/page_3.png?auth_token=YOUR_API_KEY" />

Vale l’accesso di chi possiede la chiave

Un file di una cartella si scarica solo se chi possiede la chiave può aprire quella cartella; altrimenti la risposta è 403. Senza chiave, o con una chiave revocata, è 401. Le chiavi tecniche del CRM non leggono file.

Scoping del workspace#

Header opzionali che decidono in quale workspace la richiesta legge e scrive.

x-organization-idstring
Il workspace aziendale in cui la richiesta legge e scrive: un’azienda di cui il proprietario della chiave è membro. Se lo ometti, la chiamata resta nel suo workspace personale.
x-organization-scopePERSONAL | ORGANIZATION | LEGACY
Se lo ometti vale ORGANIZATION, come per la chat: va scritto solo per LEGACY. PERSONAL è sempre il workspace personale di chi possiede la chiave, qualunque id lo accompagni. Ignorato se non è presente anche x-organization-id.Predefinito: ORGANIZATION.

Il default è prudente

Senza questi header tutto ciò che crei — cartelle, assistenti, attività, notifiche — finisce nel workspace personale di chi possiede la chiave, ed è lì che lo mostra anche l’app desktop.

Il workspace dev’essere del proprietario della chiave

Un header non basta: il box verifica che chi possiede la chiave sia membro dell’azienda indicata. Una lettura in un’azienda di cui non è membro resta nel suo workspace personale: meno risultati, non un errore. Una scrittura no: creare una cartella, un assistente, un’attività o un commento, modificare un’attività o inviare una notifica in quell’azienda risponde 403 FORBIDDEN e non scrive nulla. La chiave di un’app esterna resta nel workspace da cui l’app è stata aperta, qualunque header invii.

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, oppure la richiesta scrive in un workspace di cui non è membro.
  • 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