# Creare un token di gestione per la CLI

`POST https://api.keenauth.com/v1/environments/{environment_id}/management-tokens` · chiamato da `keenauth login`

Scambia l'accesso della CLI con un token di 10 minuti per un ambiente. Questo endpoint non viene chiamato direttamente: `keenauth login` accede con l'account della dashboard (autorizzazione del dispositivo oppure, con `--web`, un reindirizzamento loopback con PKCE) e la CLI richiede un token per ogni ambiente su cui lavora. Il token è vincolato alla chiave DPoP della CLI e include solo i permessi del ruolo della dashboard in quell'ambiente.

## Richiesta

Intestazioni:

| Intestazione | Obbligatoria | Descrizione |
| --- | --- | --- |
| `Authorization` | sì | `DPoP <access token>`: il token di accesso ricevuto dalla CLI al momento dell'accesso. |
| `DPoP` | sì | Una prova DPoP per questa richiesta, firmata con la chiave a cui è vincolato il token di accesso; contiene l'hash del token di accesso e il nonce del server. |
| `Content-Type` | sì | `application/json`. |

Corpo: un oggetto JSON vuoto, `{}`. Qualsiasi altro membro viene rifiutato con `unknown_field`. La richiesta non ha `Idempotency-Key`: ogni chiamata emette un nuovo token.

## Risposta

`201 Created` con `Cache-Control: no-store`:

| Campo | Descrizione |
| --- | --- |
| `access_token` | Il token di gestione. Va inviato come `Authorization: DPoP <token>` con una prova della stessa chiave. |
| `token_type` | Sempre `DPoP`. |
| `expires_in` | Durata in secondi: `600`. |
| `expires_at` | Fine della durata (RFC 3339, UTC). |
| `environment_id` | L'ambiente per cui è il token. |
| `audience` | La cella per cui è il token (`<region>/<cell>`). |
| `api_base` | URL base dell'API regionale che accetta il token. |
| `permissions` | I permessi dell'ambiente del ruolo della dashboard. |

La CLI conserva il token solo in memoria. Una modifica del ruolo ha effetto entro 10 minuti al massimo; quando un ruolo viene rimosso, i token aperti di quell'utente vengono revocati.

## Errori

| Stato | Codice | Quando |
| --- | --- | --- |
| 401 | `unauthenticated` | Non è stato inviato alcun token di accesso. |
| 401 | `invalid_token` | Il token di accesso non è valido, è scaduto o non appartiene alla CLI; eseguire di nuovo `keenauth login`. |
| 401 | `invalid_dpop_proof` | La prova DPoP è mancante, ripetuta oppure non corrisponde alla richiesta o alla chiave del token. |
| 401 | `use_dpop_nonce` | Riprovare con una prova che contiene il nonce dell'intestazione di risposta `DPoP-Nonce`. |
| 401 | `insufficient_user_authentication` | È richiesta l'autenticazione a più fattori (oppure, per il ruolo, una passkey o una chiave di sicurezza); eseguire di nuovo l'accesso. |
| 404 | `not_found` | L'ambiente non esiste oppure l'utente non ha un ruolo nella dashboard in esso. |
| 429 | `rate_limited` | Più di 30 token al minuto per l'utente (condivisi con la dashboard); attendere `Retry-After`. |

## Esempio

```bash
curl -X POST https://api.keenauth.com/v1/environments/env_01jb0000000000000000000000/management-tokens \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF" \
  -H "Content-Type: application/json" \
  -d '{}'
```