> For the complete documentation index, see [llms.txt](https://manuale.opencontent.it/manuali/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://manuale.opencontent.it/manuali/manuale-operativo-interno/iam-console/api-v1-e-webhook.md).

# API v1 e webhook

Le API v1 della IAM Console per i prodotti OpenCity e i webhook in ingresso.

I prodotti OpenCity gestiscono gli operatori di un Ente tramite le **API v1** della console. Oggi le usa OpenCity AI Assistant. Il contratto completo è il file `docs/openapi.yaml` del repository `core-services/iam-console`: questa pagina spiega i concetti, non ricopia il contratto.

## Autenticazione

Ogni chiamata porta un token di Authentik nell'intestazione `Authorization: Bearer <token>`. Il token può essere:

* di un **service account**, ottenuto con il grant `client_credentials` usando username e app password del service account;
* di un **operatore**, per le chiamate fatte a suo nome.

La console accetta solo token emessi per la console stessa: un token di un'altra applicazione riceve `401`. Chi chiama deve avere accesso alla console dell'Ente (un ruolo, oppure lo staff OpenCity) e le stesse autorizzazioni che avrebbe nell'interfaccia: le API non permettono nulla che la console neghi.

## Convenzioni

* **Errori**: ogni errore segue lo standard RFC 9457 (*Problem Details*): contenuto `application/problem+json` con `type`, `title`, `status` e `detail` in italiano. Il campo `type` identifica l'errore, per esempio `.../problems/operator-limit-reached`;
* **Ente non accessibile**: un Ente che non esiste e un Ente a cui non hai accesso danno la stessa risposta `404`, così le API non rivelano quali Enti esistono;
* **Operatore**: ha sempre la forma `{ user_id, email, name, username, active }`, dove `user_id` è l'UUID di Authentik;
* **Liste**: sono paginate con `page` e `page_size` (da 1 a 100, default 20) e restituiscono `{ items, total, page, page_size }`;
* **Creare un operatore**: `POST /customers/{uuid}/users` crea subito l'account in Authentik, come "Aggiungi" nella console, e manda alla persona l'email con il link per impostare la password. Il link torna anche nella risposta solo se chi chiama ha il ruolo **Link di recupero**;
* **Invitare**: `POST /customers/{uuid}/invitations` crea ancora inviti, che nella console sono disattivati. La risposta dice cosa è successo con `result`: `ADDED` (persona già esistente), `INVITED` (invito nuovo, `201`), `RENEWED` (invito esistente rinnovato);
* **Manutenzione**: durante la manutenzione ogni chiamata riceve `503` con `Retry-After: 300`.

## Webhook in ingresso

La console riceve due webhook, autenticati con un segreto nell'intestazione `X-IAM-Webhook-Secret`:

| Webhook                        | Chi lo chiama                         | Cosa fa                                                                                      |
| ------------------------------ | ------------------------------------- | -------------------------------------------------------------------------------------------- |
| `POST /api/webhooks/tm`        | Il flusso Windmill del Tenant Manager | Riallinea ruoli e accessi dell'Ente indicato                                                 |
| `POST /api/webhooks/authentik` | Authentik                             | Completa la registrazione di un operatore invitato e gestisce la cancellazione di un account |

La console non si fida del contenuto dei webhook: rilegge sempre i dati da Authentik e dal Tenant Manager. Durante la manutenzione i webhook continuano a funzionare.

## Test

Una batteria di test sulle API v1 gira contro QA con il job manuale `api-v1-qa` della pipeline di `main`. Usa l'Ente di prova `test-hurl` e Bugliano; le istruzioni sono in `tests/README.md` del repository.
