Vai al contenuto

Autenticazione

🤖 Spiega con l'intelligenza artificiale

Per garantire l’integrità e la sicurezza di tutti gli scambi di dati, 4Geeks implementa l’autenticazione tramite chiave API come standard architettonico primario per l’autorizzazione delle richieste di servizio in entrata. Secondo questo protocollo, ogni interazione programmatica deve essere accompagnata da una chiave API unica e valida; la mancata fornitura di queste credenziali comporterà un immediato rifiuto dell’autorizzazione per proteggere le risorse sensibili del sistema. Queste credenziali vengono inviate utilizzando il framework HTTP Basic Authentication, come rigorosamente definito dallo standard industriale RFC 7617, che richiede che la chiave venga passata all’interno dell’header della richiesta secondo le specifiche convenzioni di formattazione delineate nella seguente documentazione tecnica.

Authorization: Basic <base64_encoded_credentials>

Dove <base64_encoded_credentials> è la tua chiave API seguita da due punti (:) e poi codificata in Base64.

Codifica passo dopo passo

1. La tua chiave API:

sk_test_51O62xYzAbcDef123

2. Aggiungi i due punti dopo la chiave: 

sk_test_51O62xYzAbcDef123:

3. Codifica in Base64: 

c2tfdGVzdF81MU82MnhZekFiY0RlZjEyMzo=

4. Aggiungi all’header Authorization: 

Authorization: Basic c2tfdGVzdF81MU82MnhZekFiY0RlZjEyMzo=

Esempi di codice

curl -X GET 'http://api.4geeks.io/v1/customers/' \
  -H 'Authorization: Api-Key sk_test_51O62xYzAbcDef123'

import requests

api_key = "sk_test_51O62xYzAbcDef123"
response = requests.get(
    'http://api.4geeks.io/v1/customers/',
    headers={
        'Authorization': f'Api-Key {api_key}'
    }
)
print(response.json())

const apiKey = "sk_test_51O62xYzAbcDef123";

fetch("http://api.4geeks.io/v1/customers/", {
    method: "GET",
    headers: {
        Authorization: `Api-Key ${apiKey}`,
    },
})
    .then((res) => res.json())
    .then((data) => console.log(data));

import { HttpClient, HttpHeaders } from "@angular/common/http";

export class CustomerService {
    private apiKey = "sk_test_51O62xYzAbcDef123";

    constructor(private http: HttpClient) {}

    getCustomers() {
        const headers = new HttpHeaders({
            Authorization: `Api-Key ${this.apiKey}`,
        });

        return this.http.get("http://api.4geeks.io/v1/customers/", { headers });
    }
}

Gestione degli errori

400 Bad Request

Si verifica quando la richiesta manca di campi obbligatori o ha un formato non valido.

Esempio:

{
    "message": {
        "code": 400,
        "title": "Richiesta non valida",
        "content": "Si prega di fornire un campo 'type' valido: 'test' o 'live'.",
        "type": "danger"
    }
}

Cause:

  • Campo type mancante nella richiesta PATCH
  • Valore type non valido (deve essere "test" o "live")

Soluzione: Includere {"type": "test"} o {"type": "live"} nel corpo della richiesta.

401 Unauthorized

Autenticazione fallita. La chiave API non è valida, è mancante o è formattata male.

Esempi:

  1. Header Authorization mancante (Bearer Token)
Richiesta: GET /v1/auth/api-keys/ (senza l'header Authorization)
Risposta:
{
  "detail": "Le credenziali di autenticazione non sono state fornite."
}
  1. Chiave non trovata
Richiesta: Header Authorization con una chiave inesistente
Risposta:
{
    "detail": "Il token fornito non è valido per alcun tipo di token",
    "code": "token_not_valid",
    "messages": [
        {
            "token_class": "AccessToken",
            "token_type": "access",
            "message": "Il token non è valido o è scaduto"
        }
    ]
}

Soluzioni:

  • Verifica di aver incluso l’header Authorization: Bearer <Bearer_Token>
  • Verifica che la chiave non sia stata ruotata di recente
  • Testa con Postman per diagnosticare il problema

404 Not Found

Non esistono chiavi API per questo utente.

Esempio:

{
    "code": 404,
    "title": "Chiavi API non trovate",
    "content": "Nessuna chiave API trovata per questo utente. Si prega di contattare il supporto.",
    "type": "warning"
}

Soluzione: Contatta il supporto per inizializzare le chiavi API per il tuo account.

Migliori pratiche di sicurezza

Mantieni le tue chiavi al sicuro

  • Memorizza le chiavi nelle variabili d’ambiente, mai nel codice
  • Non caricare le chiavi nei sistemi di controllo versione
  • Usa file .env insieme a .gitignore
  • Ruota le chiavi ogni 3-6 mesi
  • Rigenerale immediatamente se vengono esposte

Esempio di variabile d’ambiente:

# .env
API_KEY_TEST=sk_test_51O62xYzAbcDef123
API_KEY_LIVE=sk_live_xYzAbcDef123456789
API_URL=http://api.4geeks.io

Utilizzo nell’applicazione:

import os
api_key = os.getenv('API_KEY_TEST')

Risoluzione dei problemi

Problema: 401 Unauthorized “Formato chiave API non valido”

Cause:

  • La chiave API è incompleta o troncata
  • La codifica Base64 non include i due punti (:)
  • Spazi extra nella chiave o nell’header
  • La chiave è stata ruotata di recente

Soluzioni:

  1. Copia di nuovo la chiave:
    • Vai nelle Impostazioni della dashboard → Chiavi API
    • Copia con attenzione la chiave completa

  2. Verifica la codifica Base64:

  3. Testa con Postman:

    • Crea una nuova richiesta
    • Authorization → Basic Auth
    • Username: [la tua chiave completa]
    • Password: [lascia vuoto]
    • Invia

Problema: La chiave ha smesso di funzionare dopo la rotazione

Causa: Hai ruotato la chiave ma la tua applicazione utilizza ancora quella vecchia.

Soluzione:

  1. Vai in Impostazioni → Chiavi API
  2. Copia la nuova chiave
  3. Aggiorna il tuo file .env o la configurazione
  4. Riavvia la tua applicazione

Problema: 404 “Chiavi API non trovate”

Causa: Nessuna chiave API è stata inizializzata per il tuo account.

Soluzione: Contatta il supporto per inizializzare le tue chiavi API.

Domande frequenti (FAQ)

D: Posso avere più chiavi API? A: No. Hai esattamente una chiave di test e una chiave live. Usa l’endpoint di rotazione per rigenerarle.

D: Cosa succede se espongo la mia chiave live? A: Ruotala immediatamente dalla dashboard. La chiave esposta diventerà non valida entro 1 minuto.

D: Posso usare la stessa chiave per Test e Live? A: No. Le chiavi Test e Live sono separate. Usa sempre le chiavi di test in fase di sviluppo.

D: Devo rinnovare la mia chiave API? A: A differenza dei token JWT, le chiavi API non scadono. Rimangono valide finché non le ruoti.

D: Posso usare le chiavi API con i webhook? A: No. I webhook vengono consegnati dai nostri server al tuo endpoint. Autentichi il webhook usando le firme, non le chiavi API.