Autenticazione delle API

Guida pratica per autenticare le chiamate a BASE9. Due meccanismi, due scopi.

Stai integrando…	Usa	Chi si autentica
Un sistema (gestionale, backend, automazioni)	Chiave API	l'applicazione
Il login di un utente (agente, cliente, staff) nella sua area	Token utente (JWT)	la persona

BASE9 usa un modello di identità unificato multi-persona: una credenziale (email + password) = una identità, che può assumere più aree (personas: CLIENTE, AGENTE, CRM-USER), assegnate dall'admin del tenant. Il login degli utenti avviene su una API headless di BASE9 (https://api.base9.app/v1/auth/*) — puoi quindi costruire una pagina di login custom e brandizzata.

---

A. Chiave API (sistema → BASE9)

Per le integrazioni server-to-server. La chiave è segreta, legata a un ambiente e a un livello di permessi (r o rw).

Authorization: Bearer dmk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl -H "Authorization: Bearer dmk_xxxx" "https://api.base9.app/v1/clienti?limit=10"

• Base URL: https://api.base9.app · nessun login, nessuna scadenza (vale finché attiva).
• Tienila segreta (mai nel front-end o nei repository). Se compromessa: revoca + nuova chiave.
• Errori: 401 chiave mancante/non valida · 403 scrittura con chiave in sola lettura.

---

B. Token utente — login (agenti, clienti, staff)

Il login avviene sull'API BASE9. Base URL: https://api.base9.app.

B1 — Login email + password

curl -X POST https://api.base9.app/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"mario@x.it","password":"..."}'

Il campo tenant è opzionale. La risposta include sempre l'elenco dei tenant accessibili dall'identità → utile per un CRM ad accesso unico: l'utente fa un solo login e poi sceglie l'ambiente.

Esito — successo:

{ "data": {
  "tokens": { "id_token":"...", "access_token":"...", "refresh_token":"...", "expires_in":3600 },
  "tenants": [
    { "tenant_id":"ID_TENANT",   "personas":["AGENTE","CLIENTE"] },
    { "tenant_id":"ID_TENANT_2", "personas":["AGENTE"] }
  ]
} }

Il token è scoped su un tenant (quello passato in tenant, o il primo se omesso). Per entrare in un tenant specifico dopo la scelta dell'utente, ri-scopa il token con /v1/auth/refresh (vedi B4) — oppure passa tenant già al login (utile per pagine brandizzate su un singolo ambiente). Esito — challenge (serve un passo in più):

{ "data": { "challenge": "SOFTWARE_TOKEN_MFA", "session": "..." } }

Usa sempre l'id_token come Bearer sulle API.

B2 — Verifica in due passaggi (MFA TOTP, complementare)

Il 2° fattore è opzionale (obbligatorio per le personas CRM/AGENTE se il tenant lo richiede) e usa un'app authenticator (nessuna dipendenza da email/SMS).

Attivazione (utente autenticato):

curl -X POST .../v1/auth/mfa/setup        -d '{"access_token":"...","email":"mario@x.it"}'
# → { "data": { "secret":"...", "otpauth_uri":"otpauth://totp/BASE9:mario@x.it?secret=..." } }  (mostra come QR)
curl -X POST .../v1/auth/mfa/verify-setup -d '{"access_token":"...","code":"123456"}'

Se al login arriva SOFTWARE_TOKEN_MFA:

curl -X POST .../v1/auth/mfa/verify -d '{"email":"mario@x.it","session":"...","code":"123456","tenant":"..."}'

B3 — Primo accesso (nuova password)

Se il login torna NEW_PASSWORD_REQUIRED:

curl -X POST .../v1/auth/new-password -d '{"email":"...","session":"...","new_password":"...","tenant":"..."}'

B4 — Rinnovo token e cambio tenant

curl -X POST .../v1/auth/refresh -d '{"refresh_token":"...","tenant":"ALTRO_TENANT"}'

Passando un tenant diverso (dove l'identità ha un'area) si ottiene un token per quel tenant → cambio tenant/area senza re-login.

B5 — Password: reset e cambio

curl -X POST .../v1/auth/password/forgot  -d '{"email":"..."}'                          # invia codice via email
curl -X POST .../v1/auth/password/reset   -d '{"email":"...","code":"...","new_password":"..."}'
curl -X POST .../v1/auth/password/change  -d '{"access_token":"...","old_password":"...","new_password":"..."}'

Usare il token

GET https://api.base9.app/v1/me/agente
Authorization: Bearer <id_token>

⚠️ Usa l'id_token (contiene identità, personas e risorse), non l'access_token.

---

C. Contesto utente & aree — GET /v1/me/context

Dopo il login, il frontend chiama questo endpoint per sapere quali aree mostrare e quali moduli sono abilitati (i moduli non sono nel token):

curl -H "Authorization: Bearer $ID_TOKEN" https://api.base9.app/v1/me/context

{ "data": {
  "tenant": "ID_TENANT",
  "personas": ["CLIENTE","AGENTE"],
  "agente_id": "A123", "cliente_id": "C456", "crm_role": null,
  "modules_per_persona": { "CLIENTE": {"bolletta":"r"}, "AGENTE": {"contratti":"rw","fatturazione":"r"} },
  "tenants_disponibili": [ {"tenant_id":"ID_TENANT","personas":["CLIENTE","AGENTE"]} ]
} }

Il frontend disegna i box AREA CLIENTE / AREA AGENTI / CRM in base a personas; dentro ogni area i modules_per_persona gate-ano le funzioni; tenants_disponibili alimenta il selettore tenant.

D. Aree self-service — /v1/me/*

La persona è implicita dalla route; il resource_id è preso SEMPRE dal token (isolamento garantito: ogni utente vede solo i propri dati).

• AGENTE: /v1/me/agente, /v1/me/agente/contratti, /…/contratti/{id}, /…/andamento, /…/superiori
• CLIENTE: /v1/me/cliente, /v1/me/cliente/contatti

E. Amministrazione utenti e aree (admin del tenant)

L'admin assegna a un'identità le personas, la risorsa e i moduli:

GET    /v1/admin/users
POST   /v1/admin/users                          {"email":"..."}
PUT    /v1/admin/users/{sub}/grants/AGENTE      {"resource_id":"A...","modules":{"contratti":"rw"}}
DELETE /v1/admin/users/{sub}/grants/{persona}

---

Riferimento rapido

	Chiave API	Token utente (JWT)
Per	Sistemi / integrazioni	Persone (agenti, clienti, staff)
Login	— (nessun login)	POST https://api.base9.app/v1/auth/login
Header API	Authorization: Bearer dmk_…	Authorization: Bearer <id_token>
Scadenza	nessuna (finché attiva)	id_token ~1h · refresh 30 giorni
Endpoint dati	https://api.base9.app/v1/*	https://api.base9.app/v1/me/*

Errori di autenticazione

Codice	Significato	Cosa fare
401 not_authorized	token/credenziali mancanti o non validi	rifai login o verifica l'header
403 permission_denied	persona/permesso non sufficiente	usa il token con la persona/modulo corretto
429 rate_limited	troppi tentativi	attendi e riprova

Guida completa per sviluppatori: /developers/authentication.md · dettaglio endpoint: API Reference · visione d'insieme: Accessi.