Autenticazione

Ogni richiesta all’API pubblica porta la chiave nell’header X-API-Key:

X-API-Key: 8f14e45fceea167a5a36dedd4bea2543a1b0c9f2e4d7b8a6c3e5f9d2a4b6c8e0

Authorization: Bearer non funziona

Authorization: Bearer <chiave> è riservato ai token di sessione dell’app: una chiave API passata lì viene rifiutata con 403. Usa sempre l’header dedicato X-API-Key.

Creare una chiave

La chiave si crea da Impostazioni → API Keys → Nuova chiave e si vede in chiaro una sola volta, alla creazione. Ne conserviamo solo l’impronta SHA-256 e le prime sei cifre (per riconoscerla nell’elenco): nessuno può rileggerla — né noi, né un amministratore, né chi rubasse una copia del database. Se la perdi, la revochi e ne crei un’altra.

Una chiave agisce sul tuo account dall’esterno, senza sessione utente: trattala come una password.

Permessi (scope)

Una chiave non può fare nulla per cui non abbia il permesso: si concedono uno per uno, alla creazione o in modifica.

Permesso	Cosa apre
read_devices	Elenco e anagrafica dei dispositivi
read_locations	Ultima posizione nota
read_history	Storico delle posizioni
read_history_summary	Storico in forma aggregata
read_events	Eventi della flotta
send_commands	Coda comandi — in API v2 solo in lettura

Senza il permesso, la risposta è 403:

{ "error": "API key senza permesso: read_devices" }

Nota

L’invio dei comandi non è esposto in v2: da una chiave si può leggere la coda, non muovere un mezzo. È una scelta di sicurezza (il taglio motore da remoto è una capacità sensibile), non una dimenticanza.

Restrizione per IP (opzionale)

A ogni chiave puoi legare una lista di indirizzi ammessi, fino a 50 voci: IPv4 singoli o in notazione CIDR (10.0.0.0/24), IPv6 solo come indirizzo esatto. Una chiamata che arriva da un IP fuori lista viene rifiutata con 403 e codice API_KEY_IP_BLOCKED, anche se la chiave è valida. Allowlist vuota o assente = nessuna restrizione.

Rate limit

Limite	Valore
Per chiave, al minuto	120
Per chiave, all’ora	1000
Per indirizzo IP, al minuto	120

Oltre il limite la risposta è 429. Le risposte non portano header X-RateLimit-* né Retry-After: regola il tuo client sui numeri qui sopra.

Esempio: prima chiamata autenticata

cURL

curl https://api.aitrack.it/api/v2/devices?limit=10 \
  -H "X-API-Key: $AITRACK_API_KEY"

Node.js

const response = await fetch('https://api.aitrack.it/api/v2/devices?limit=10', {
  headers: { 'X-API-Key': process.env.AITRACK_API_KEY },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`Aitrack API error: ${JSON.stringify(error)}`);
}

const { data, meta } = await response.json();
console.log(data, meta);

Python

import os
import requests

response = requests.get(
    "https://api.aitrack.it/api/v2/devices",
    headers={"X-API-Key": os.environ["AITRACK_API_KEY"]},
    params={"limit": 10},
    timeout=10,
)
response.raise_for_status()
body = response.json()
print(body["data"], body["meta"])

Revoca

Se sospetti che una chiave sia trapelata, revocala subito da API Keys: smette di funzionare alla chiamata successiva. Le chiavi già revocate non tornano attive.

Tenere al sicuro una chiave

• Mettila in una variabile d’ambiente. Mai nel codice del sito, mai in un repository: una chiave in un repo pubblico è un accesso aperto alla tua flotta.
• Una chiave per integrazione, così revocarne una non rompe le altre.
• Limita gli IP quando puoi: una chiave rubata da un indirizzo non ammesso non serve a nulla.