Come funzionano le chiavi API? - Centro assistenza

Le chiavi API sono le tue credenziali di autenticazione per accedere all’API di Cathopic. Comprendere come funzionano è essenziale per un’integrazione API sicura ed efficace.

Che cos’è una chiave API?

Una chiave API è un token segreto univoco che identifica la tua applicazione e la autorizza ad accedere all’API di Cathopic:

Una lunga stringa alfanumerica (ad es. sk_live_abc123xyz789...)
Agisce sia come autenticazione sia come autorizzazione
Collegata al tuo account Cathopic e alla fatturazione
Può essere attiva o inattiva

Ciclo di vita della chiave

Creazione:

Genera le chiavi in Impostazioni → API
Assegna a ogni chiave un nome descrittivo ("Sito Web di Produzione", "Staging", "App Mobile")
Copia l’intera chiave subito: viene mostrata solo una volta
Conserva in modo sicuro (variabili d’ambiente, secrets manager, password manager)

Utilizzo:

Includi nell’header HTTP x-api-key con ogni richiesta
Le chiavi vengono validate lato server ad ogni richiesta
Tutti gli utilizzi dell’API vengono tracciati e addebitati al tuo account

Disattivazione:

Le chiavi possono essere disabilitate temporaneamente senza eliminarle
Utile per la risoluzione dei problemi o per mettere in pausa una specifica integrazione
Può essere riattivata in qualsiasi momento

Eliminazione:

Rimuove definitivamente la chiave
Non può essere annullata o recuperata
Tutte le richieste con quella chiave falliranno immediatamente

Linee guida per la gestione delle chiavi

Sicurezza:

Non inserire mai le chiavi nel controllo versione: Usa i file .env e aggiungili a .gitignore
Non esporre mai nel codice lato client: Le chiavi API devono essere usate solo lato server
Usa variabili d’ambiente: Conserva le chiavi in process.env.CATHOPIC_API_KEY o equivalente
Ruota regolarmente le chiavi: Cambiale periodicamente (trimestralmente o dopo cambi di membri del team)
Usa chiavi separate per ogni ambiente: Chiavi diverse per sviluppo, staging e produzione

Organizzazione:

Nomi descrittivi: Dai alle chiavi un nome in base allo scopo: "Sito Web di Produzione", "App iOS", "Sistema Email"
Traccia la proprietà: Registra quale membro del team ha creato ogni chiave
Audit regolari: Rivedi le chiavi attive ogni mese e rimuovi quelle non utilizzate

Più chiavi API

Puoi creare più chiavi API per scopi diversi:

Per ambiente: Chiavi separate per sviluppo, staging e produzione
Per applicazione: Chiavi diverse per sito web, app mobile, strumenti interni
Per membro del team: Chiavi individuali per i developer (più facile da tracciare e revocare)

Tutte le chiavi sotto il tuo account condividono la stessa fatturazione. L’utilizzo di tutte le chiavi viene combinato nella tua fattura mensile.

Monitoraggio dell’utilizzo delle chiavi

Traccia l’attività per ogni chiave:

Vai su Impostazioni → API
Visualizza l’elenco di tutte le chiavi con le date dell’ultimo utilizzo
Clicca su una chiave per vedere statistiche dettagliate sull’utilizzo
Monitora attività non previste

Cosa fare se una chiave è compromessa

Se ritieni che una chiave API sia stata esposta:

Elimina o disattiva immediatamente la chiave in Impostazioni → API
Genera una nuova chiave di sostituzione
Aggiorna la tua applicazione con la nuova chiave
Rivedi i log di utilizzo per eventuali attività sospette
Contatta l’assistenza se vedi utilizzo non autorizzato

Esempio: conservare le chiavi in modo sicuro

Node.js con variabili d’ambiente:

// File .env (aggiungi a .gitignore!)
CATHOPIC_API_KEY=sk_live_abc123xyz789...
// Il tuo codice
require('dotenv').config();
const apiKey = process.env.CATHOPIC_API_KEY;
fetch('https://api.cathopic.com/resources', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ query: 'Jesus' })
});

Python con variabili d’ambiente:

import os
import requests
api_key = os.environ.get('CATHOPIC_API_KEY')
response = requests.post(
    'https://api.cathopic.com/resources',
    headers={'x-api-key': api_key},
    json={'query': 'Jesus'}
)