Appearance
Accessi a BASE9
Capitolo pilota — completo. Gli altri capitoli del manuale seguono questa stessa impostazione: obiettivo → come funziona → passi → risultato atteso → riferimento tecnico.
BASE9 prevede due modalità di accesso distinte, pensate per due scopi diversi. Sceglierla correttamente è il primo passo di ogni integrazione.
| Modalità | A cosa serve | Chi la usa |
|---|---|---|
| Chiave API | Far dialogare un sistema esterno (es. il gestionale del partner) con BASE9, in automatico | I sistemi / gli sviluppatori dell'integratore |
| Area riservata | Dare a una persona (agente o cliente) un accesso personale per consultare i propri dati | Gli utenti finali, dal browser |
Non sono alternative: spesso convivono. Un partner integra i propri sistemi via Chiave API e, allo stesso tempo, offre ai propri agenti e clienti un'Area riservata.
💻 Stai integrando le API? Per le procedure tecniche di autenticazione (chiamate, endpoint, token, esempi cURL/Amplify) vedi la pagina dedicata Autenticazione delle API.
1. Chiave API (integrazioni tra sistemi)
Obiettivo
Permettere a un'applicazione — non a una persona — di leggere e scrivere dati su BASE9 in modo automatico e sicuro. È il canale che usa lo sviluppatore dell'integratore per collegare il proprio software a BASE9.
Come funziona
A ogni partner viene assegnata una chiave API: una stringa segreta riconoscibile dal prefisso dmk_. La chiave è legata a:
- un solo ambiente (un "tenant", cioè lo spazio dati dedicato del partner);
- un livello di permessi: sola lettura oppure lettura e scrittura.
Ogni richiesta verso BASE9 include la chiave; BASE9 la riconosce, capisce a quale ambiente appartiene e applica i permessi.
Passi
- Richiesta della chiave — Il team BASE9 genera la chiave per l'ambiente del partner e ne definisce il livello di permessi. [DA DEFINIRE: canale ufficiale di richiesta]
- Consegna sicura — La chiave viene consegnata una sola volta e va custodita come una password.
- Configurazione — Lo sviluppatore la inserisce nel proprio sistema, che la invierà a ogni chiamata.
- Uso — Da quel momento il sistema del partner può operare su BASE9 secondo i permessi concessi.
In termini tecnici, la chiave viaggia nell'intestazione di ogni richiesta:
Authorization: Bearer dmk_xxxxxxxxxxxxxxxxPer l'elenco completo delle operazioni disponibili con la Chiave API, vedi l'API Reference (schema di sicurezza ApiKeyAuth).
Buone pratiche
- Riservatezza: la chiave non va mai pubblicata (no codice client, no email in chiaro, no repository).
- Permessi minimi: se l'integrazione deve solo leggere, si richiede una chiave in sola lettura.
- Una chiave per ambiente/uso: facilita la revoca mirata senza impatti sugli altri.
- Rotazione: in caso di sospetto, la chiave si revoca e se ne emette una nuova.
Risultato atteso
Il sistema del partner opera su BASE9 in autonomia, in modo tracciato e con permessi controllati.
2. Area riservata (accesso personale di agenti e clienti)
Obiettivo
Offrire a ogni agente e a ogni cliente un accesso personale, dal browser, per consultare solo i propri dati (profilo, contratti, e — per gli agenti — la propria rete). Ogni persona vede esclusivamente ciò che la riguarda.
Come funziona
L'accesso all'area riservata non è pubblico: è il partner (admin del tenant) a provisionare la persona, assegnandole una o più aree (personas: CLIENTE, AGENTE, CRM-USER) con i relativi permessi sui moduli. Tecnicamente si usa l'API admin grant (POST /v1/admin/users + PUT /v1/admin/users/{sub}/grants/{persona}); guida passo-passo: Area riservata multi-persona.
Identità unificata multi-persona. Una stessa persona (una sola email + password) può avere più aree contemporaneamente: es. un CLIENTE che è anche AGENTE, dopo il login, vede sia l'Area Cliente sia l'Area Agenti, secondo ciò che l'admin gli ha abilitato. Le aree e i permessi disponibili si ottengono da
GET /v1/me/context.
Il primo accesso, passo per passo
Il login avviene su POST https://api.base9.app/v1/auth/login (email + password).
| Fase | Cosa fa la persona | Cosa succede |
|---|---|---|
| 1 | Inserisce email + password | Se è il primo accesso con password provvisoria, BASE9 chiede di impostarne una nuova |
| 2 | (se richiesto) imposta la nuova password e attiva il 2FA (TOTP) se il tenant lo richiede per la sua area | Il login si completa e riceve i token |
| 3 | Il frontend chiama GET /v1/me/context | Ottiene le proprie aree e i moduli abilitati |
È sempre disponibile la procedura di "password dimenticata" in autonomia. Dettagli tecnici (MFA, refresh, cambio tenant): Autenticazione.
Cosa vede l'utente nella propria area
- Agente: il proprio profilo, i contratti a lui attribuiti, la propria posizione nella rete commerciale (e, in prospettiva, le provvigioni).
- Cliente: il proprio profilo e i propri recapiti (e, in prospettiva, forniture e documenti).
In ogni caso, mai i dati di un altro agente o cliente: l'isolamento è garantito da BASE9.
Revoca
Il partner può revocare in qualsiasi momento l'accesso di una persona: da quel momento non potrà più entrare.
Per i dettagli tecnici dell'invito, della revoca e delle informazioni esposte, vedi l'API Reference (sezione Portale, schema di sicurezza PortalJWT).
Risultato atteso
Agenti e clienti dispongono di un accesso personale e sicuro alle proprie informazioni, gestito interamente dal partner.
In sintesi
- Chiave API → i sistemi del partner parlano con BASE9. Segreta, con permessi, per ambiente.
- Area riservata → le persone (agenti, clienti) consultano i propri dati. Su invito, con password personale, isolata.
Per ogni dettaglio tecnico (parametri, formati, codici di errore) il riferimento è sempre l'API Reference; questo manuale ne spiega il significato e l'uso.