Riferimento API

Frontdoor espone un'API JSON sotto /api.

Convenzioni

• Ogni risposta di errore è in JSON, con un error leggibile e un code stabile in snake_case.
• Le richieste che modificano dati con il cookie di sessione devono arrivare da Frontdoor stesso o da un'origine elencata in CORS_ALLOWED_ORIGINS.

Livelli di autenticazione

Livello	Significato
No	Endpoint pubblico
Sessione	Il cookie frontdoor_token, o lo stesso token come Authorization: Bearer
Admin lettura	Sessione di un owner, admin o admin_readonly
Admin modifica	Sessione di un owner o admin
Owner	Sessione di un owner
Chiave API	L'header X-API-Key con il valore di ADMIN_API_KEY

API bulk delle app

Gli endpoint bulk sono pensati per le pipeline di CI e di automazione che gestiscono il catalogo delle app.

Metodo	Endpoint	Descrizione
GET	/api/apps/bulk	Esporta tutte le app con i metadati completi, attive e inattive
POST	/api/apps/bulk	Crea o aggiorna più app con una sola chiamata, abbinate per slug

Entrambi richiedono l'header X-API-Key e rispondono 503 quando ADMIN_API_KEY non è configurata.

curl -s https://frontdoor.contoso.com/api/apps/bulk \
  -H 'X-API-Key: your-api-key'

Stato e accesso

Metodo	Endpoint	Autenticazione	Descrizione
GET	/api/health	No	Controllo dello stato
GET	/api/auth/microsoft	No	Avvia l'accesso Microsoft (PKCE; ?redirect=<app slug> facoltativo)
GET	/api/auth/microsoft/callback	No	Callback dell'accesso Microsoft
GET	/api/auth/me	Sessione	Utente corrente e preferenze (impersonation è null, oppure { sessionId, actor, expiresAt, reason } mentre si agisce come un utente)
PUT	/api/auth/me/preferences	Sessione	Aggiorna le proprie preferenze (vista Home, lingua, fuso orario, tema, ordine delle app, preferiti, tour)
POST	/api/auth/home-activity	Sessione	Registra l'attività nella Home (con limitazione di frequenza)
POST	/api/auth/logout	No	Esce (cancella il cookie)
GET	/api/auth/dev-status	No	Indica se il Login Dev è disponibile
POST	/api/auth/dev-login	No	Login Dev (solo in sviluppo, mai in produzione)
POST	/api/auth/verify-sso-token	Token e audience nel corpo	Introspezione del token SSO per le app satellite (vedi Autenticazione delle app satellite)

Impersonation

Metodo	Endpoint	Autenticazione	Descrizione
POST	/api/impersonation	Admin lettura	Inizia ad agire come un utente (corpo { userId, reason }; restituisce 201 { sessionId, expiresAt })
POST	/api/impersonation/stop	Sessione	Termina l'impersonation (restituisce { ok: true })

Branding e manutenzione

Metodo	Endpoint	Autenticazione	Descrizione
GET	/api/branding	No	Branding e valori predefiniti del tenant
PUT	/api/branding	Owner	Aggiorna il branding e i valori predefiniti del tenant
GET	/api/branding/logo	No	Logo aziendale
GET	/api/branding/cache	Owner	Dimensione della cache avatar, della cache icone e del database
POST	/api/branding/avatars/refresh	Owner	Svuota la cache degli avatar
POST	/api/branding/app-icons/cleanup	Owner	Rimuove i file delle icone non usati
POST	/api/branding/database/compact	Owner	Compatta il database (VACUUM)

App

Metodo	Endpoint	Autenticazione	Descrizione
GET	/api/apps	Sessione	App visibili all'utente corrente
GET	/api/apps/all	Admin lettura	Tutte le app, comprese quelle inattive
GET	/api/apps/:id/icon	No	Icona dell'app
GET	/api/apps/:slug/sso-redirect	Sessione	Apre un'app (redirect o SSO POST, accesso registrato)
GET	/api/apps/:slug/entra-redirect	Sessione	Apre un'app Entra tramite MyApps (accesso registrato)
POST	/api/apps/:slug/track-access	Sessione	Registra l'accesso a un'app aperta direttamente
POST	/api/apps	Admin modifica	Crea un'app
POST	/api/apps/:id/clone	Admin modifica	Prepara una copia di un'app (non viene salvato nulla)
PUT	/api/apps/:id	Admin modifica	Aggiorna un'app (vengono scritti solo i campi modificati)
POST	/api/apps/:id/groups	Admin modifica	Imposta i gruppi che possono aprire un'app
DELETE	/api/apps/:id	Admin modifica	Elimina un'app
POST	/api/apps/restore-defaults	Admin modifica	Ripristina le app demo
GET	/api/apps/bulk	Chiave API	Esportazione bulk delle app (metadati completi)
POST	/api/apps/bulk	Chiave API	Upsert bulk delle app per slug

Utenti

Metodo	Endpoint	Autenticazione	Descrizione
GET	/api/users	Admin lettura	Elenca gli utenti
GET	/api/users/:id	Admin lettura	Dettaglio dell'utente (gruppi, app visibili)
GET	/api/users/:id/avatar	Sessione	Avatar dell'utente
PUT	/api/users/:id/preferences	Admin modifica	Aggiorna o reimposta le preferenze di un utente
PUT	/api/users/:id/role	Admin modifica	Cambia il ruolo
PUT	/api/users/:id/active	Admin modifica	Attiva o disattiva
DELETE	/api/users/:id	Admin modifica	Elimina un utente

Gruppi

Metodo	Endpoint	Autenticazione	Descrizione
GET	/api/groups	Admin lettura	Elenca i gruppi
GET	/api/groups/:id	Admin lettura	Dettaglio del gruppo (membri, app, collegamenti)
POST	/api/groups	Admin modifica	Crea un gruppo
PUT	/api/groups/:id	Admin modifica	Aggiorna un gruppo
DELETE	/api/groups/:id	Admin modifica	Elimina un gruppo
POST	/api/groups/bulk-delete	Admin modifica	Elimina più gruppi
POST	/api/groups/:id/members	Admin modifica	Aggiunge membri
DELETE	/api/groups/:id/members/:userId	Admin modifica	Rimuove un membro
POST	/api/groups/:id/apps	Admin modifica	Dà a un gruppo l'accesso alle app
DELETE	/api/groups/:id/apps/:appId	Admin modifica	Rimuove un'app da un gruppo
POST	/api/groups/:id/apps/transfer	Admin modifica	Copia o sposta tutte le app in un altro gruppo
POST	/api/groups/:id/groups	Admin modifica	Collega gruppi figli
DELETE	/api/groups/:id/groups/:childGroupId	Admin modifica	Scollega un gruppo figlio
POST	/api/groups/:id/entra-groups	Admin modifica	Collega gruppi Entra
DELETE	/api/groups/:id/entra-groups/:entraGroupId	Admin modifica	Scollega un gruppo Entra
GET	/api/groups/entra/candidates	Admin lettura	Gruppi Entra rilevati e disponibili per l'importazione
POST	/api/groups/entra/import	Admin modifica	Importa i gruppi Entra rilevati
POST	/api/groups/entra/force-sync	Admin modifica	Sincronizza le appartenenze Entra di tutti gli utenti collegati

Libreria media

Metodo	Endpoint	Autenticazione	Descrizione
GET	/api/media-assets	Admin lettura	Libreria media (icone e loghi)
GET	/api/media-assets/large-icons	Admin lettura	Icone delle app più grandi di 200 KB, con dimensioni in pixel e indicazione se si possono ottimizzare
GET	/api/media-assets/:id	Admin lettura	Dettaglio di un asset media
GET	/api/media-assets/:id/file	Admin lettura	File di un asset media (solo immagini)
DELETE	/api/media-assets/:id	Admin modifica	Elimina un asset media non usato

Log e audit

Metodo	Endpoint	Autenticazione	Descrizione
GET	/api/logs	Owner	Log degli accessi (paginati)
GET	/api/logs/top-apps	Owner	App aperte più spesso
POST	/api/logs/clear-access	Owner	Svuota subito il log degli accessi
GET	/api/logs/audit	Owner	Log di audit (paginato; exclude_target_types=auth nasconde gli accessi). Alias: /api/logs/rbac-audit

Backup

Metodo	Endpoint	Autenticazione	Descrizione
GET	/api/backups/export	Owner	Scarica un backup
POST	/api/backups/export-jobs	Owner	Avvia un backup in background
GET	/api/backups/export-jobs/:jobId/events	Owner	Avanzamento del backup (server-sent events)
GET	/api/backups/export-jobs/:jobId/file	Owner	Scarica il backup completato
GET	/api/backups/database	Owner	Copia grezza del database (.db)
POST	/api/backups/verify	Owner	Verifica un backup senza modificare nulla (upload binario)
POST	/api/backups/restore	Owner	Ripristina un backup (upload binario)

Plugin

Gli endpoint dei plugin (/api/plugins/*) rispondono 404 finché la piattaforma dei plugin è bloccata. Vedi Plugin.