UC-014 — API Key Management

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

Scenari reali

Onboarding sviluppatore: Il team lead crea una API Key dedicata per una nuova integrazione, limitandola alle sole operazioni di cui l'integrazione ha bisogno.
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 di vita completo di una API Key: verifica dell'ambito, creazione, listing e revoca.

Prerequisiti

Account attivo sulla piattaforma Qlara
Almeno una API Key esistente per autenticare le chiamate di gestione
La chiave chiamante deve essere autorizzata all'operazione AUTHENTICATION

Passo 1 — Verifica cosa può fare la tua chiave attuale

Prima di creare una chiave, ispeziona quella con cui stai chiamando. Una nuova chiave può ricevere solo le operazioni che la chiave chiamante già possiede: questo endpoint ti dice quindi qual è l'ambito massimo a tua disposizione.

curl -X GET https://api.qlara.ai/api/partner-gateway/v1/authentication/me \
  -H "X-Api-Key: YOUR_API_KEY"

Risposta — Chiave corrente

{
  "id": 1,
  "companyId": 100,
  "userId": 42,
  "username": "api-user",
  "trafficType": 0,
  "operations": ["SMS", "RCS", "WHATSAPP"],
  "creationDate": "2025-03-10 14:30:00.000+0100",
  "lastUpdateDate": "2025-03-10 14:30:00.000+0100"
}

La chiave non viaggia mai nell'URL

La chiave viene letta dall'header X-Api-Key, quindi questo endpoint non accetta parametri e non restituisce mai il valore della chiave. Sostituisce il rimosso GET /authentication/{value}, che richiedeva la chiave in chiaro nell'URL.

Passo 2 — Crea una nuova API Key

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

curl -X POST https://api.qlara.ai/api/partner-gateway/v1/authentication \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "userId": 4618,
    "trafficType": 0,
    "operations": ["SMS", "RCS", "WHATSAPP"]
  }'

Campo	Obbligatorio	Descrizione
`userId`	Sì	ID dell'utente a cui appartiene la chiave. Le chiavi senza `userId` sono orfane e non possono essere eliminate tramite questa API.
`operations`	Sì	Operazioni consentite alla chiave. Deve essere un sottoinsieme non vuoto delle operazioni possedute dalla chiave chiamante.
`trafficType`	No	Identificativo del tipo di traffico (`0` = standard). Lascia `0` salvo diversa indicazione.

Valori ammessi per operations: CONTACTS, SOCIALS, INBOX, AUTOMATION, MEDIA, MESSAGES, EMAIL, REPORT, CALENDAR, SUBSCRIPTION, AUTHENTICATION, RCS, WHATSAPP, SMS, CAMPAIGNS, EXPORTS, WEBHOOKS.

Risposta — Key creata

{
  "id": 1,
  "companyId": 100,
  "apiKey": "ak_live_abc123def456",
  "username": null,
  "trafficType": 0,
  "operations": ["SMS", "RCS", "WHATSAPP"],
  "creationDate": "2025-03-10 14:30:00.000+0100"
}

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 è più recuperabile da alcun endpoint.

Nessuno username alla creazione

Le chiavi create qui sono identificate da id e userId e non hanno username: il campo username nella risposta è sempre null. Un username inviato nel body viene ignorato.

Dietro le quinte — Generazione e ambito della chiave

Autorizzazione: il gateway risolve la chiave chiamante e verifica che sia autorizzata all'operazione AUTHENTICATION.
Verifica dell'ambito: le operations richieste vengono confrontate con quelle della chiave chiamante. Tutto ciò che le eccede viene rifiutato con 403 — una chiave non può concedere privilegi che non possiede.
Generazione: la stringa della chiave viene generata e restituita una sola volta, in questa risposta.
Associazione: la chiave viene collegata all'azienda della chiave chiamante e allo userId indicato.

Passo 3 — Elenca le chiavi esistenti

Recupera le API Key associate al tuo account. Aggiungi il parametro di query opzionale userId per filtrare per proprietario.

curl -X GET https://api.qlara.ai/api/partner-gateway/v1/authentication \
  -H "X-Api-Key: YOUR_API_KEY"

Risposta — Elenco key

[
  {
    "id": 1,
    "companyId": 100,
    "userId": 4618,
    "username": "api-user",
    "trafficType": 0,
    "operations": ["SMS", "RCS", "WHATSAPP"],
    "creationDate": "2025-03-10 14:30:00.000+0100",
    "lastUpdateDate": "2025-03-10 14:30:00.000+0100"
  },
  {
    "id": 2,
    "companyId": 100,
    "userId": 5172,
    "username": null,
    "trafficType": 0,
    "operations": ["CONTACTS", "CAMPAIGNS", "MESSAGES"],
    "creationDate": "2026-01-15 09:00:00.000+0100",
    "lastUpdateDate": "2026-01-15 09:00:00.000+0100"
  }
]

Questo endpoint non restituisce mai il valore completo della chiave, ma solo i suoi metadati.

Passo 4 — Revoca una chiave compromessa

Elimina una chiave che non deve più essere utilizzata. L'id della chiave va nel path.

curl -X DELETE https://api.qlara.ai/api/partner-gateway/v1/authentication/1 \
  -H "X-Api-Key: YOUR_API_KEY"

Risposta — Key revocata

204 No Content — la risposta non ha body. Una chiave inesistente restituisce 404.

Dietro le quinte — Cosa succede dopo la revoca

Invalidazione immediata: la chiave viene rimossa dal Key Store. Le richieste successive che la usano ricevono 401 Unauthorized.
Nessun rollback: l'eliminazione è irreversibile. Per ripristinare l'accesso, crea una nuova chiave.
Chiavi orfane: una chiave salvata senza userId non può essere eliminata tramite questa API — è questo il motivo per cui userId è obbligatorio alla creazione.

Risultato atteso

Passo	Azione	Risultato
1	`GET /authentication/me`	`200 OK` con le operazioni della chiave chiamante
2	`POST /authentication`	`201 Created`, `apiKey` completa restituita una sola volta
3	`GET /authentication`	`200 OK` con l'array delle chiavi (senza i valori)
4	`DELETE /authentication/{id}`	`204 No Content`

Esempio completo end-to-end

Scenario FinSecure: rotazione trimestrale delle chiavi.

BASE=https://api.qlara.ai/api/partner-gateway/v1

# 1. Verifica l'ambito disponibile alla chiave chiamante
curl -s -X GET "$BASE/authentication/me" \
  -H "X-Api-Key: $CURRENT_KEY" | jq '.operations'

# 2. Crea la nuova chiave, con lo stesso ambito
NEW_KEY=$(curl -s -X POST "$BASE/authentication" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $CURRENT_KEY" \
  -d '{
    "userId": 4618,
    "trafficType": 0,
    "operations": ["SMS", "RCS", "WHATSAPP"]
  }' | jq -r '.apiKey')

echo "Nuova chiave: $NEW_KEY"

# 3. Verifica che la nuova chiave funzioni e controlla il suo ambito
curl -s -X GET "$BASE/authentication/me" \
  -H "X-Api-Key: $NEW_KEY" | jq '{id, operations}'

# 4. Revoca la vecchia chiave tramite il suo id
curl -s -o /dev/null -w "%{http_code}\n" \
  -X DELETE "$BASE/authentication/$OLD_KEY_ID" \
  -H "X-Api-Key: $NEW_KEY"

Varianti

Creare una chiave a privilegio minimo per ogni integrazione

Limita ogni chiave al più piccolo insieme di operazioni che ne copre il compito:

# Chiave di solo invio
curl -X POST https://api.qlara.ai/api/partner-gateway/v1/authentication \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{"userId": 4618, "operations": ["SMS"]}'

# Chiave per marketing automation
curl -X POST https://api.qlara.ai/api/partner-gateway/v1/authentication \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{"userId": 4618, "operations": ["CONTACTS", "CAMPAIGNS", "MESSAGES"]}'

Errori comuni

400 Bad Request — `operations` mancante o vuoto

{
  "status": "fail",
  "data": {
    "operations": "operations is required: a key with no operations cannot authenticate any request"
  }
}

Soluzione: invia un array operations non vuoto. Una chiave senza operazioni non può autenticare nulla.

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 usata per gestire le altre sia ancora attiva e autorizzata all'operazione AUTHENTICATION.

403 Forbidden — Le operazioni richieste eccedono il tuo ambito

{
  "status": "fail",
  "data": {
    "operations": "Requested operations exceed the caller's own scope"
  }
}

Soluzione: una chiave non può concedere privilegi che non possiede. Chiama GET /authentication/me per vedere cosa possiede la chiave chiamante, poi richiedi un sottoinsieme di quelle operazioni.

404 Not Found — La chiave non esiste

Soluzione: controlla l'id nel path confrontandolo con l'elenco restituito da GET /authentication. Le chiavi salvate senza userId non possono essere eliminate tramite questa API.

Prossimi passi

UC-016 — Monitorare Credito e Abbonamento: Verifica lo stato del tuo abbonamento e il 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

Scenari reali​

Flusso di gestione​

Prerequisiti​

Passo 1 — Verifica cosa può fare la tua chiave attuale​

Risposta — Chiave corrente​

Passo 2 — Crea una nuova API Key​

Risposta — Key creata​

Passo 3 — Elenca le chiavi esistenti​

Risposta — Elenco key​

Passo 4 — Revoca una chiave compromessa​

Risposta — Key revocata​

Risultato atteso​

Esempio completo end-to-end​

Varianti​

Creare una chiave a privilegio minimo per ogni integrazione​

Errori comuni​

400 Bad Request — operations mancante o vuoto​

401 Unauthorized — Chiave non valida​

403 Forbidden — Le operazioni richieste eccedono il tuo ambito​

404 Not Found — La chiave non esiste​

Prossimi passi​

Riferimenti​