Chiavi API

Le API Keys rappresentano un metodo di autenticazione alternativo ai token PASETO, ideale per integrazioni programmatiche con il nostro servizio. Ogni API Key è associata a un utente e può avere permessi specifici (scopes).

Formato delle API Keys

Le API Keys hanno il seguente formato:

npf_<prefisso>_<valore-segreto>

Esempio:

npf_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

Creazione di una Nuova API Key

Per generare una nuova API Key, effettua una richiesta POST:

POST /api/v1/api-keys

Parametri della Richiesta

{
  "name": "Nome della chiave",
  "scopes": ["scope1", "scope2"],
  "expiresIn": 365
}

Campi:

• name: Nome descrittivo dell'API Key (obbligatorio)
• scopes: Array di permessi associati alla chiave (opzionale)
• expiresIn: Durata in giorni della validità della chiave (opzionale, default: 365 giorni)

Risposta

{
  "status": "success",
  "data": {
    "id": "uuid-della-chiave",
    "name": "Nome della chiave",
    "key": "npf_prefisso_chiavesegreta",
    "prefix": "npf_prefisso",
    "scopes": ["scope1", "scope2"],
    "expiresAt": "2023-12-31T23:59:59.999Z",
    "createdAt": "2023-01-01T00:00:00.000Z"
  },
  "message": "API Key creata con successo. Salva la chiave in un posto sicuro, non sarà più visibile dopo."
}

Utilizzo delle API Keys

Le API Keys possono essere fornite in uno dei seguenti modi:

1. Nell'header Authorization

Authorization: Bearer npf_prefisso_chiavesegreta

oppure

Authorization: ApiKey npf_prefisso_chiavesegreta

2. Nell'header X-API-Key

X-API-Key: npf_prefisso_chiavesegreta

3. Come parametro di query

https://api.example.com/api/v1/endpoint?api_key=npf_prefisso_chiavesegreta

Gestione delle API Keys

Elenco delle API Keys

GET /api/v1/api-keys

Questa richiesta restituisce tutte le API Keys associate all'utente corrente (senza il valore completo della chiave, solo il prefisso per sicurezza).

Risposta:

{
  "status": "success",
  "data": [
    {
      "id": "uuid-1",
      "name": "Chiave Produzione",
      "prefix": "npf_prefisso1",
      "scopes": ["organizations:read", "inpforms:read"],
      "expiresAt": "2024-12-31T23:59:59.999Z",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "active": true
    }
  ]
}

Revoca di un'API Key

DELETE /api/v1/api-keys/:id

Dove :id è l'ID dell'API Key da revocare.

Disattivazione di un'API Key

POST /api/v1/api-keys/:id/deactivate

Questa operazione disattiva temporaneamente una API Key senza eliminarla dal sistema. Può essere utile quando si desidera sospendere un'integrazione senza perdere completamente la chiave.

Gestione degli Scopes

Le API Keys utilizzano un sistema di scope per controllare i permessi. Gli scope seguono il formato <risorsa>:<operazione>.

Scope Disponibili per Utenti Pubblici

Per la documentazione pubblica, l'unico scope disponibile è:

• organizations:read - Lettura e ricerca organizzazioni (pubblico)

Esempio di Creazione API Key con Scope

{
  "name": "My API Key",
  "scopes": ["organizations:read"]
}

Esempio - Nessuno Scope Specificato

Se non specifichi scope, viene assegnato automaticamente lo scope di default sicuro:

{
  "name": "My API Key"
}

Risultato - Scope Default:

{
  "scopes": ["organizations:read"]
  // Scope read-only sicuro assegnato automaticamente
}

Best Practices di Sicurezza

1. Protezione delle chiavi: Tratta le API Keys come password. Non condividerle e conservale in modo sicuro.
2. Privilegi minimi: Utilizza gli scope per limitare i permessi di ciascuna API Key.
3. Rotazione regolare: Cambia periodicamente le tue API Keys per ridurre il rischio in caso di esposizione.
4. Una chiave per integrazione: Usa chiavi separate per diversi servizi o integrazioni.
5. Monitoraggio: Tieni traccia dell'utilizzo delle tue API Keys e revoca immediatamente quelle compromesse.

Documentazione Correlata

• PASETO Tokens - Autenticazione alternativa per utenti
• Guida: Ottenere Token - Guida passo-passo per ottenere i tuoi token
• Guida: Gestire Token - Come gestire il ciclo di vita dei token
• Ricerca Organizzazioni - Documentazione endpoint di ricerca