Chiavi API

Maintainer: Aether365 Team Destinatari: Sviluppatori Ambito: Endpoint per la gestione delle chiavi API

Le chiavi API vengono utilizzate per autenticare le richieste alla REST API senza una sessione utente.

Ogni chiave API è legata all'account tenant che l'ha creata. Le chiavi API hanno lo stesso livello di accesso di un membro del team - possono leggere e scrivere tutti i dati del tenant ma non possono modificare la fatturazione o le impostazioni del piano.

Elencare le chiavi API

Restituisce tutte le chiavi API attive per il tenant.

GET /tenants/me/api-keys

INFO

Per sicurezza, il valore completo della chiave viene restituito solo una volta - al momento della creazione. Le successive richieste di elenco mostrano solo il prefisso della chiave e i metadati.

Richiesta di esempio

curl https://api.aether365.io/tenants/me/api-keys \
  -H "Authorization: Bearer <token>"

Risposta di esempio

{
  "success": true,
  "data": [
    {
      "id": "key_abc123",
      "name": "CI pipeline",
      "prefix": "ae_live_abc1",
      "createdAt": "2026-03-01T09:00:00Z",
      "lastUsedAt": "2026-04-10T14:23:00Z"
    }
  ]
}

Campi della risposta

Campo	Tipo	Descrizione
id	string	Identificativo della chiave
name	string	Nome visualizzato
prefix	string	Primi 12 caratteri della chiave (per identificazione)
createdAt	string	Timestamp ISO 8601
lastUsedAt	string o null	Timestamp ISO 8601 dell'ultima richiesta autenticata

---

Creare una chiave API

Crea una nuova chiave API. Il valore completo della chiave viene restituito una sola volta e non può essere recuperato successivamente.

POST /tenants/me/api-keys

Corpo della richiesta

{
  "name": "CI pipeline"
}

Campo	Tipo	Obbligatorio	Descrizione
name	string	Sì	Nome visualizzato per la chiave

Richiesta di esempio

curl -X POST https://api.aether365.io/tenants/me/api-keys \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI pipeline"}'

Risposta di esempio

{
  "success": true,
  "data": {
    "id": "key_abc123",
    "name": "CI pipeline",
    "key": "ae_live_abc123xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "prefix": "ae_live_abc1",
    "createdAt": "2026-04-12T10:00:00Z",
    "lastUsedAt": null
  }
}

Salva la chiave immediatamente

Il campo key viene restituito solo in questa risposta. Non può essere recuperato successivamente. Salvalo in un gestore di segreti (GitHub Actions secrets, HashiCorp Vault, ecc.) immediatamente.

---

Eliminare una chiave API

Revoca permanentemente una chiave API. Qualsiasi richiesta che utilizza questa chiave restituirà immediatamente 401.

DELETE /tenants/me/api-keys/{keyId}

Richiesta di esempio

curl -X DELETE https://api.aether365.io/tenants/me/api-keys/key_abc123 \
  -H "Authorization: Bearer <token>"

Risposta di esempio

{
  "success": true,
  "data": null
}

---

Utilizzare una chiave API

Passa la chiave API come token Bearer nell'header Authorization:

curl https://api.aether365.io/tenants/me/scans \
  -H "Authorization: Bearer ae_live_abc123xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Le chiavi API funzionano allo stesso modo dei token di sessione per tutti gli endpoint. Non scadono, ma puoi ruotarle creando una nuova chiave ed eliminando quella vecchia.

Limiti di frequenza

L'API è limitata a 120 richieste al minuto per chiave API. Le richieste che superano il limite ricevono una risposta 429 Too Many Requests. La risposta include un header Retry-After che indica quando riprovare.