Chiavi API

Una chiave API autorizza un sistema esterno, per esempio il tuo ERP, a usare la REST API v1 di exoCortex: aprire ticket, leggerne lo stato e aggiungere commenti. Ogni chiave appartiene a un tenant e vede solo i ticket di quel tenant.

Creare una chiave

1. In exoCortex Core apri Integrations → API keys. Serve un ruolo amministrativo, per esempio it_admin o integration_admin.
2. Dai alla chiave un nome che dica chi la usa, per esempio «Connettore ERP».
3. Scegli gli scope, cioè cosa la chiave può fare (vedi sotto).
4. Copia la chiave completa e salvala nel gestore di segreti del sistema che la userà. exoCortex la mostra una sola volta e ne conserva solo un’impronta: se la perdi, crei una chiave nuova.

La chiave ha la forma nhk.<keyid>.<secret>. Il keyid identifica la chiave nell’elenco; il secret resta solo a te.

Scope

Scope	Cosa permette
tickets:create	Aprire ticket
tickets:read	Leggere lo stato di un ticket
tickets:comment	Aggiungere commenti a un ticket
tickets:*	Tutte le operazioni sui ticket
*	Tutto quello che l’API v1 permette

Assegna a ogni chiave solo gli scope che le servono. Una chiave senza scope ha accesso completo all’API v1: è ammesso, ma sconsigliato.

Usare la chiave

Invia la chiave nell’intestazione Authorization di ogni richiesta:

POST /api/v1/tickets HTTP/1.1
Host: exocortex-api.ai-exo-cortex.com
Authorization: Bearer nhk.9f2c4e1a7b3d.…
Content-Type: application/json
Idempotency-Key: 6b1f0c4e-2a7d-4b39-9e51-8c3d2f7a1b60

{ "subject": "Payment gateway returns HTTP 502", "priority": "High" }

In alternativa puoi usare l’intestazione X-NH-API-Key. Il tenant non si indica: exoCortex lo ricava dalla chiave.

Usa sempre Idempotency-Key quando apri un ticket: se ripeti la richiesta con la stessa chiave di idempotenza, ricevi il ticket già creato invece di un duplicato.

Limiti di frequenza

Ogni chiave ha un limite di richieste: il valore predefinito è 600 richieste ogni 60 secondi. Ogni risposta indica a che punto sei:

Intestazione	Significato
RateLimit-Limit	Richieste ammesse nella finestra
RateLimit-Remaining	Richieste ancora disponibili
RateLimit-Reset	Secondi alla nuova finestra
Retry-After	Solo con la risposta 429: secondi da attendere prima di riprovare

Errori

Gli errori dell’API v1 restituiscono un JSON con ok: false, un messaggio leggibile in error e un codice stabile in code. Basa la logica del tuo client sul code, non sul messaggio.

code	Stato HTTP	Cosa fare
missing_api_key	401	Aggiungi l’intestazione Authorization
invalid_api_key	401	Controlla la chiave: può essere sbagliata o revocata
insufficient_scope	403	Aggiungi alla chiave lo scope indicato in required_scope
api_key_disabled	403	La chiave è disattivata: usa una chiave attiva
validation_error	400	Correggi il campo indicato in field
not_found	404	Il ticket non esiste o non appartiene al tenant della chiave
rate_limited	429	Attendi i secondi indicati in Retry-After
ingest_failed	500	Riprova con la stessa Idempotency-Key

exoCortex può aggiungere nuovi codici: se ne ricevi uno che non conosci, decidi in base allo stato HTTP.

Revocare una chiave

Da Integrations → API keys revochi una chiave quando un sistema non la usa più o se pensi che sia stata esposta. La revoca è immediata. L’elenco mostra anche l’ultimo utilizzo di ogni chiave: ti aiuta a trovare le chiavi inattive.

Chiavi nh_… deprecate

Le chiavi nel vecchio formato nh_… funzionano fino al 30 giugno 2027. Le risposte a queste chiavi contengono le intestazioni Deprecation e Sunset. Per migrare crea una chiave nhk. con gli scope necessari, aggiorna il sistema che la usa, poi revoca la vecchia chiave.