UC-014 — API Key Management

Campo	Valore
ID	UC-014
Obiettivo	Creare, elencare e revocare API Key per il proprio account
Canale	Tutti
Complessità	Base
Tempo stimato	5 minuti
API coinvolte	GET /api/partner-gateway/v1/authentication, POST /api/partner-gateway/v1/authentication, DELETE /api/partner-gateway/v1/authentication

Scenari reali

• Onboarding sviluppatore: Il team lead crea una nuova API Key dedicata per lo sviluppatore appena assunto, limitando l'accesso al solo ambiente di staging.
• Rotazione chiavi periodica: L'azienda FinSecure ruota le proprie API Key ogni 90 giorni come richiesto dalla policy di sicurezza interna.
• Revocare chiave compromessa: Un developer ha accidentalmente committato una API Key su un repository pubblico e deve revocarla immediatamente.

Flusso di gestione

Il diagramma mostra il ciclo completo di vita di una API Key: creazione, consultazione e revoca.

Prerequisiti

• Account attivo sulla piattaforma Qlara
• Almeno una API Key esistente per autenticare le chiamate di gestione
• Permessi di amministrazione sul proprio account

Step 1 — Crea una nuova API Key

Invoca l'endpoint di creazione per generare una nuova chiave.

curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/authentication \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "name": "staging-dev-marco",
    "description": "Chiave per ambiente staging - Marco Rossi"
  }'

Response — Key creata

{
  "id": "key_a1b2c3d4e5f6",
  "name": "staging-dev-marco",
  "description": "Chiave per ambiente staging - Marco Rossi",
  "apiKey": "pg_live_9f8e7d6c5b4a3210...",
  "createdAt": "2026-04-09T10:00:00+02:00",
  "status": "ACTIVE"
}

:::warning Salva subito la chiave Il campo apiKey viene mostrato solo al momento della creazione. Copialo e conservalo in un secret manager (es. Vault, AWS Secrets Manager). Non sara più recuperabile. :::

Dietro le quinte — Generazione della chiave

1. Validazione: Il gateway verifica che la richiesta provenga da un utente con permessi di admin.
2. Generazione: Viene generato un token crittograficamente sicuro (256 bit) con prefisso pg_live_ per facilitare l'identificazione.
3. Hashing: La chiave viene hashata (bcrypt) prima dello storage — il gateway conserva solo l'hash, non il valore in chiaro.
4. Associazione: La chiave viene collegata all'account e ai permessi configurati.

Step 2 — Elenca le chiavi attive

Recupera la lista di tutte le API Key associate al tuo account.

curl -X GET https://lora-api.agiletelecom.com/api/partner-gateway/v1/authentication \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Lista chiavi

{
  "keys": [
    {
      "id": "key_a1b2c3d4e5f6",
      "name": "staging-dev-marco",
      "status": "ACTIVE",
      "createdAt": "2026-04-09T10:00:00+02:00",
      "lastUsedAt": "2026-04-09T14:30:00+02:00"
    },
    {
      "id": "key_z9y8x7w6v5u4",
      "name": "production-main",
      "status": "ACTIVE",
      "createdAt": "2026-01-15T09:00:00+01:00",
      "lastUsedAt": "2026-04-09T15:00:00+02:00"
    }
  ]
}

:::tip Monitora lastUsedAt Il campo lastUsedAt ti aiuta a identificare chiavi inutilizzate. Una chiave non usata da mesi potrebbe essere candidata alla revoca. :::

Step 3 — Revoca una chiave compromessa

Elimina immediatamente una chiave che non deve più essere utilizzata.

curl -X DELETE https://lora-api.agiletelecom.com/api/partner-gateway/v1/authentication \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "id": "key_a1b2c3d4e5f6"
  }'

Response — Chiave revocata

{
  "id": "key_a1b2c3d4e5f6",
  "status": "REVOKED",
  "revokedAt": "2026-04-09T15:30:00+02:00"
}

Dietro le quinte — Cosa succede dopo la revoca

1. Invalidazione immediata: La chiave viene marcata come REVOKED nel Key Store. Tutte le richieste successive con questa chiave riceveranno 401 Unauthorized.
2. Propagazione cache: L'invalidazione si propaga ai nodi di caching entro 30 secondi.
3. Audit log: L'evento di revoca viene registrato nel log di audit con timestamp, IP e utente che ha eseguito l'operazione.
4. Nessun rollback: La revoca e irreversibile. Per riabilitare l'accesso, crea una nuova chiave.

Risultato atteso

Step	Azione	Risultato
1	POST /authentication	Nuova API Key creata, status: "ACTIVE"
2	GET /authentication	Lista completa delle chiavi con lastUsedAt
3	DELETE /authentication	Chiave revocata, status: "REVOKED"

Esempio completo end-to-end

Scenario FinSecure: rotazione chiave trimestrale.

# 1. Crea la nuova chiave
NEW_KEY=$(curl -s -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/authentication \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "name": "production-q2-2026",
    "description": "Chiave produzione Q2 2026"
  }' | jq -r '.apiKey')

echo "Nuova chiave: $NEW_KEY"

# 2. Verifica che la nuova chiave funzioni
curl -s -X GET https://lora-api.agiletelecom.com/api/partner-gateway/v1/authentication \
  -H "X-Api-Key: $NEW_KEY" | jq '.keys | length'

# 3. Revoca la vecchia chiave
curl -s -X DELETE https://lora-api.agiletelecom.com/api/partner-gateway/v1/authentication \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $NEW_KEY" \
  -d '{"id": "key_old_q1_2026"}' | jq .

Varianti

Creare una chiave con scadenza

Aggiungi un campo expiresAt per creare chiavi con scadenza automatica:

curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/authentication \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "name": "temp-contractor",
    "description": "Chiave temporanea per consulente esterno",
    "expiresAt": "2026-06-30T23:59:59+02:00"
  }'

Errori comuni

401 Unauthorized — Chiave non valida

{
  "status": "fail",
  "data": {
    "authentication": "Invalid or missing API key"
  }
}

Soluzione: Verifica che l'header X-Api-Key sia presente e che la chiave utilizzata per gestire le altre chiavi sia ancora attiva.

403 Forbidden — Permessi insufficienti

{
  "status": "fail",
  "data": {
    "authorization": "Insufficient permissions to manage API keys"
  }
}

Soluzione: Solo gli utenti con ruolo admin possono creare o revocare chiavi. Contatta l'amministratore del tuo account.

Prossimi passi

• UC-016 — Monitorare Credito e Abbonamento: Verifica lo stato del tuo abbonamento e credito residuo
• UC-001 — Invio SMS Singolo: Usa la tua nuova chiave per inviare il primo messaggio
• Guida Autenticazione: Dettagli completi su API Key e Basic Auth

Riferimenti

• API Reference — Authentication