Autenticazione

Ogni richiesta all’API di Sursa porta una chiave API, oppure un token di accesso OAuth di un’applicazione, nell’intestazione Authorization:

Authorization: Bearer kb_3f9c…

La chiave identifica l’organizzazione e decide cosa può vedere e modificare la richiesta: il suo ruolo, i suoi ambiti, il suo profilo dati e le sue raccolte. Sull’indirizzo dell’API non ci sono sessioni né cookie. Ogni richiesta viene autenticata da sola, quindi puoi inviare richieste in parallelo e da più server con la stessa chiave.

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"

Le integrazioni precedenti possono inviare invece la chiave in un’intestazione X-API-Key. È ancora accettata, ma il codice nuovo dovrebbe usare Authorization: Bearer.

Tipi di credenziali

Credenziale	Forma	Dove funziona
Chiave API dell’organizzazione	`kb_…`	Ogni endpoint dell’API, entro il suo ruolo, i suoi ambiti, il suo profilo dati e le sue raccolte.
Chiave di una fonte personalizzata	`kbsrc_…`	Solo gli endpoint di invio della sua fonte personalizzata (`/v1/push/sources/{source_id}/…`).
Token di accesso OAuth	`kbat_…`	Gli endpoint del riferimento API, entro gli ambiti del token. Un token ottenuto da `POST /oauth/token` con un codice di autorizzazione agisce per conto del dipendente che ha dato il consenso; un token `client_credentials` agisce per l’organizzazione, come una chiave API. È valido per 1 ora.

Tutte le credenziali si inviano allo stesso modo. Una chiave di fonte personalizzata non può leggere, cercare né modificare nulla al di fuori della sua fonte; usala dove la chiave viene conservata da terzi, per esempio da una piattaforma di integrazione.

Errori di autenticazione

Stato e codice	Cosa significa	Cosa fare
`401` `auth.not_authenticated`	Nessuna chiave, una chiave scritta in modo errato o una chiave revocata.	Controlla l’intestazione e il valore della chiave.
`401` `api_keys.expired`	La chiave ha superato la data di scadenza.	Crea una nuova chiave e sostituisci quella vecchia.
`401` `sources.push_key_invalid`	Una chiave di fonte personalizzata è errata, revocata o appartiene a un’altra fonte.	Controlla la chiave e l’ID della fonte nel percorso.
`401` `oauth.token_expired`	Il token di accesso OAuth è scaduto.	Ottienine uno nuovo con il token di aggiornamento.
`403` `api_keys.scope`	La chiave non ha un ambito per questa operazione.	Aggiungi l’ambito o usa una chiave che lo abbia.
`403` `api_keys.feature_disabled`	Il piano dell’organizzazione non include le chiavi API.	Contatta l’amministratore dell’organizzazione.
`403` `api_keys.ip_not_allowed`	La richiesta proviene da un indirizzo che non rientra tra gli indirizzi consentiti della chiave.	Chiama da una rete consentita oppure modifica gli indirizzi della chiave.
`403` `api_keys.mcp_only`	È stata usata una chiave MCP personale al di fuori dell’endpoint `/mcp`.	Per l’API usa una chiave API dell’organizzazione.
`403` `oauth.operation_not_allowed`	L’operazione non fa parte dell’API pubblica, quindi un token OAuth non può chiamarla.	Usa un’operazione del riferimento API.
`403` `org.suspended`	L’organizzazione è sospesa. I suoi dati vengono conservati.	Contatta l’amministratore dell’organizzazione.

403 significa che la richiesta è stata autenticata ma non è consentita. Un oggetto che la chiave non può vedere risponde 404, come un oggetto che non esiste, quindi una chiave non può scoprire cosa c’è al di fuori del suo accesso.

Operare come un profilo dati

Una chiave con il ruolo admin può controllare cosa vedrebbe un altro gruppo di persone: l’intestazione X-View-As esegue una richiesta come un profilo dati e, facoltativamente, come un ruolo.

curl "https://api.sursa.com/v1/cards?limit=20" \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "X-View-As: employee:viewer"

Le richieste in questa modalità possono solo leggere: qualsiasi modifica restituisce 403 con il codice view_as.read_only. Un token OAuth, o una chiave senza il ruolo admin, non può usare X-View-As: la richiesta riceve 403 con il codice view_as.admin_key_required. Un’intestazione che non indica nessun profilo esistente riceve 400 con il codice view_as.invalid_header.

Applicazioni nel browser

L’API consente richieste da qualsiasi origine web (Access-Control-Allow-Origin: *) e non usa mai i cookie, quindi una pagina può chiamarla con fetch. La chiave in quel caso si trova nella pagina ed è visibile a chi la usa. Chiama l’API dal browser solo con una chiave che sei disposto a mostrare a quegli utenti, per esempio una chiave viewer limitata alle raccolte pubbliche, oppure metti un tuo server tra il browser e Sursa.

Cosa può fare solo un dipendente

Una chiave API dell’organizzazione agisce per l’organizzazione, non per una persona. Due parti dell’API appartengono alle persone, quindi funzionano solo con un token che agisce per conto di un dipendente: una sessione in Sursa o un token di accesso OAuth rilasciato con il consenso del dipendente.

Le conversazioni appartengono a una persona. Una chiave API dell’organizzazione vede in GET /v1/conversations solo le conversazioni che ha avviato lei stessa. L’API pubblica non ha nessuna operazione che avvii una conversazione, quindi per una chiave l’elenco di norma è vuoto, e le conversazioni dei dipendenti non le vengono mai mostrate. Le domande senza conversazione, con POST /v1/ask o POST /v1/chat, funzionano con qualsiasi chiave che abbia l’ambito ask. Per elencare le conversazioni di un dipendente e leggere la cronologia di una di esse con GET /v1/conversations/{conv_id}, chiama l’API con un token OAuth per conto di quel dipendente. Il token vede solo le conversazioni di quel dipendente; qualsiasi altra conversazione risponde 404 con il codice conversations.not_found.

Solo un dipendente verifica una scheda. La verifica conferma che una persona ha controllato il contenuto, quindi POST /v1/cards/{card_id}/verification/verify e POST /v1/cards/{card_id}/verify richiedono una sessione o un token OAuth per conto di un dipendente che può verificare la scheda. Con una chiave API dell’organizzazione, o con un token client_credentials, rispondono 400 con il codice cards.verify_user_account_required. I controlli abituali vengono prima: una scheda che la chiave non può vedere risponde 404, e una chiave che non ha il permesso di verificarla riceve 403.