> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Configurare l'autenticazione Didit tramite API

> Con Didit attiva metodi di accesso, impostazioni, branding e protezione dal tuo codice, con un grant approvato o una chiave API dedicata.

Didit Authentication ti permette di abilitare i metodi di accesso e di leggere via API le impostazioni della tua applicazione. Usa un'autorizzazione approvata dal titolare oppure una chiave API denominata con lo scope `authentication`.

> [!WARNING]
>
> Authentication è una novità. Configura prima un metodo in un'applicazione sandbox, poi nella tua applicazione live.

Ogni chiamata riportata di seguito viene effettuata sull'API di gestione di Authentication della tua applicazione. `MANAGEMENT_BASE` è:

```text theme={null}
https://apx.didit.me/auth/v2/organizations/{org_id}/applications/{application_id}/authentication/
```

Gli stessi percorsi sono descritti da `openapi-authentication.json` sotto il tag `Setup`, da cui gli SDK lato server vengono rigenerati.

## Quale credenziale usare

È utilizzabile una qualsiasi delle tre credenziali, e ciascuna è limitata a ciò che il suo titolare ha approvato.

| Credenziale | Inviata come | Cosa può fare |
| - | - | - |
| Chiave API con nome e ambito `authentication` | `x-api-key: <key>` | Configura la propria applicazione e la legge. Una chiave con `read` può solo leggere la configurazione; `write` può leggerla e modificarla. |
| Concessione approvata dal titolare con `didit:management` | `Authorization: Bearer <access_token>` | Configura le applicazioni delle organizzazioni approvate al momento del consenso, nei limiti del ruolo della persona. |
| Sessione della console | `Authorization: Bearer <console session token>` | Legge o modifica le impostazioni in base all'appartenenza della persona all'organizzazione e al suo ruolo. Le viste per gli utenti finali richiedono anch'esse una sessione della console e i permessi appropriati. |

Queste credenziali vengono rifiutate con `403` su ogni percorso di configurazione, indipendentemente da ciò che la richiesta chiede:

* Il **segreto primario** dell'applicazione.
* Un token ottenuto da `POST /programmatic/login`, che viene emesso per l'applicazione e non per la console.
* Una chiave **senza** l'ambito `authentication`, inclusa una chiave creata con ogni risorsa al livello più alto: queste vengono elencate con accesso completo, mantengono `scopes` vuoto e non sono accettate su questi percorsi.
* Una chiave di **un'altra applicazione**, una concessione limitata a `didit:verification`, e una concessione approvata per un'altra organizzazione.

Una richiesta senza alcuna credenziale riceve `401`. Una concessione o una chiave mantengono inoltre i propri limiti: la concessione i suoi ambiti, le organizzazioni e il ruolo della persona, la chiave i suoi ambiti, l'elenco di indirizzi IP consentiti e la scadenza.

## Approva l'accesso

### Con una chiave API con nome

Apri **Developers -> API keys** nella [Business Console](https://business.didit.me) e crea una chiave per l'applicazione che stai configurando. Assegnale la risorsa `authentication` con autorizzazione di **lettura** o **scrittura**: la lettura copre ogni chiamata che legge la configurazione (`GET`); la scrittura copre ogni chiamata che la modifica (`POST`, `PUT`, `PATCH`, `DELETE`) e permette anche di leggerla. Consulta [Chiavi API](https://docs.didit.me/it/console/api-keys.md) per la scadenza, le liste di indirizzi IP consentiti e la rotazione; una chiave appartiene a una sola applicazione e funziona solo per quella.

### Tramite una connessione MCP

Un agente connesso al server MCP di Didit usa l'autorizzazione approvata dal suo titolare nella schermata di consenso, con `didit:management`. Consulta [Autenticazione MCP](https://docs.didit.me/it/integration/mcp/authentication.md#accedi-con-didit).

### Per un proprietario senza password

Il flusso di autorizzazione tramite codice dispositivo ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)) permette a un proprietario che accede con Google, una passkey o un codice inviato via email di approvare lo stesso accesso da qualsiasi browser, senza digitare una password. Consulta [accedere senza browser](https://docs.didit.me/it/integration/mcp/authentication.md#accedi-senza-browser-codice-dispositivo).

## Attiva il codice via email

`PUT methods/{name}/` accetta `enabled` e nient'altro per un metodo che non richiede credenziali.

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/code/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
```

La risposta riporta il metodo nello stato attuale:

```json theme={null}
{"name": "code", "enabled": true}
```

Quando rileggi la configurazione, la voce per il codice via email include `credential_source: null`. I metodi sempre attivi non possono essere disattivati: quella richiesta risponde `{"enabled": "always_on"}`.

## Abilitare Google

Un metodo social richiede le credenziali della tua app OAuth, oppure quelle dell'app di test di Didit su un'applicazione sandbox.

### Con la tua app Google

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/google/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "credentials": {"client_id": "1234.apps.googleusercontent.com", "client_secret": "GOCSPX-..."}}'
```

Registra presso il tuo provider il `callback_uri` restituito dalla risposta. Il segreto è solo in scrittura: nessuna risposta lo restituisce, e `client_id` è l'unica parte che puoi rileggere. Attivare un metodo senza credenziali, quando prima non ne erano state salvate, restituisce `{"credentials": "required"}`.

### Con l'app di test di Didit (`didit_test`)

Un'**applicazione sandbox** può usare le app social di Didit al posto delle tue, il che basta per completare una configurazione e verificarne il funzionamento:

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/google/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "credential_source": "didit_test"}'
```

`didit_test` copre **Google, Microsoft, Apple e GitHub**, solo su applicazioni sandbox:

| Risposta | Quando |
| - | - |
| `{"credential_source": "sandbox_only"}` | L'applicazione è in produzione. Le app di test non servono mai accessi in produzione. |
| `{"credential_source": "unavailable"}` | La distribuzione non ha un'app di test per quel provider, quindi il metodo resta disattivato. |
| `200` con `configured: true` | L'app di test supporta il metodo e l'accesso ospitato lo propone. |

La `GET` sulla configurazione indica in `didit_test_credentials` i provider che un'app di test può servire per questa applicazione; il valore è `false` per tutti e quattro su un'applicazione in produzione.

## Leggere nuovamente la configurazione

`GET` su `MANAGEMENT_BASE` restituisce la configurazione completa: ogni metodo con `enabled` e `credential_source`, oltre agli URL di callback, alle regole di sessione e alla policy di registrazione.

```bash theme={null}
curl --fail-with-body "$MANAGEMENT_BASE" -H "x-api-key: $DIDIT_API_KEY"
```

```json theme={null}
{
  "enabled": true,
  "methods": [
    {"name": "code", "enabled": true, "credential_source": null},
    {"name": "google", "enabled": true, "credential_source": "didit_test", "configured": true, "client_id": "didit-test-google"},
    {"name": "password", "enabled": false, "credential_source": null}
  ],
  "didit_test_credentials": {"google": true, "microsoft": true, "apple": true, "github": true},
  "redirect_uris": ["https://app.example.com/auth/callback"]
}
```

Anche i metodi disabilitati sono elencati, quindi una sola richiesta `GET` indica cosa è attivo e cosa no. `enabled` in alto è `false` quando Authentication è disattivata per l'applicazione. Qualsiasi modifica alla configurazione effettuata con un'autorizzazione di gestione o con una chiave API nominata restituisce `409` con `{"detail": "product_disabled"}` e non scrive nulla. Nessuna chiamata di configurazione attiva Authentication: una persona la attiva per l'applicazione nella console, e le tue chiamate funzionano da quel momento in poi.

## Il resto della configurazione

| Percorso, sotto `MANAGEMENT_BASE` | Metodi | Cosa contiene |
| - | - | - |
| `settings/` | `GET`, `PATCH` | Accesso degli agenti, organizzazioni, la policy MFA, il ruolo predefinito dei membri, gli eventi webhook disattivati |
| `onboarding/` | `GET`, `PATCH` | Quali passaggi di configurazione sono completati e se le persone accedono tramite la pagina ospitata o le tue schermate |
| `branding/` | `GET`, `PATCH` | I testi delle pagine ospitate e i link legali (logo e colori provengono da Personalizzazione) |
| `protection/` | `GET`, `PATCH` | Le policy di protezione dai bot ([protezione dai bot](https://docs.didit.me/it/authentication/bot-protection.md)) |
| `verified/` | `GET`, `PATCH` | Il livello di verifica in fase di registrazione, le regole di step-up e i claim del token |
| `emails/`, `emails/{key}/` | `GET` | Le email di accesso inviate da questa applicazione e un'anteprima renderizzata |
| `domain/` | `GET`, `PUT`, `DELETE` | L'origine ospitata e il dominio di accesso personalizzato |
| `domain/verify/`, `domain/activate/` | `POST` | Verifica il DNS e il certificato del dominio, quindi lo imposta come origine canonica |
| `native-apps/` | `GET`, `PUT` | Le app iOS e Android che condividono le passkey dell'applicazione |

Un'autorizzazione o una chiave ottiene la configurazione e i relativi contatori, mai i dati degli utenti finali: `users/`, `sessions/`, `sign-ins/`, `overview/`, le organizzazioni clienti, i ruoli, le importazioni, le sessioni degli agenti e le email di test richiedono ancora una sessione nella console.

L'impostazione `agent_humans_only` si applica all'intera applicazione. Solo il proprietario o un amministratore dell'organizzazione può modificarla. Una chiave nominativa riceve `403 owner_or_admin_required`. Attivare l'impostazione richiede inoltre una passkey registrata (`passkey_required`).

## Errori

| Risposta | Significato |
| - | - |
| `401` | Nessuna credenziale. |
| `403` | Una credenziale che non può configurare questa applicazione, oppure uno dei suoi limiti: `ip_not_allowed`, una chiave scaduta, una chiave di sola lettura su un endpoint di scrittura. |
| `409 {"detail": "product_disabled"}` | L'autenticazione è disattivata per l'applicazione, quindi una modifica alla configurazione effettuata con una concessione di accesso o una chiave viene rifiutata. Una persona la attiva dalla console. |
| `400 {"<field>": "<code>"}` | `sandbox_only`, `unavailable`, `not_supported`, `required`, `always_on`, `method_unavailable`, `unknown_field`. |
| `404` | La risorsa richiesta non è stata trovata. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.