KEPLIN Docs

API & GraphQL Chiavi di API

Chiavi di API

Generare, delimitare e revocare le chiavi API — l'accesso dei sistemi esterni al GraphQL delle tue app.

I sistemi esterni — un ERP che sincronizza clienti, un sito che crea richieste, un'integrazione di fatturazione — chiamano il GraphQL delle app con una chiave API: un segreto inviato nell'header x-api-key di ogni richiesta. Le chiavi sono gestite a livello di piattaforma e condivise tra le app: ogni chiave ha un ambito — scegli le app e, per ogni app, tutti gli endpoint o solo alcuni. Un'integrazione di fatturazione può, per esempio, leggere gli account nell'app Gestione Clienti e scrivere documenti in un'altra app, con un'unica chiave.

Nota

Le chiavi appartengono a chi amministra la piattaforma: la pagina Chiavi API è disponibile solo agli account di amministratore.

La pagina Chiavi API

Apri il menu Chiavi API nella navigazione globale. L'elenco mostra tutte le chiavi della piattaforma:

Colonna Che cos'è
Nome Il nome che hai dato alla chiave — identifica l'integrazione.
Prefisso I primi caratteri della chiave (es. amk_A1b2C3…) — servono a riconoscere quale sia quale senza mai mostrare la chiave intera.
Ambito Le app a cui dà accesso e, per ogni app, "tutti gli endpoint" o l'elenco di quelli concessi.
Stato attiva o revocata.
Ultimo utilizzo Quando la chiave è stata usata l'ultima volta — mai, se non è ancora successo.

La pagina Chiavi API, con l'ambito e l'ultimo utilizzo di ogni chiave.
La pagina Chiavi API, con l'ambito e l'ultimo utilizzo di ogni chiave.

Dica

La colonna Ultimo utilizzo è il tuo strumento di pulizia: una chiave con mesi di inutilizzo è candidata alla revoca.

Creare una chiave API

  1. Premi Nuova chiave API.
  2. Dai un Nome della chiave — es. integrazione-fatturazione.
  3. In Ambito — app ed endpoint consentiti, seleziona le app da includere. Per impostazione predefinita, ogni app selezionata concede "Tutti gli endpoint di questa app."
  4. Per stringere l'accesso in un'app, seleziona Restringi a endpoint specifici e scegli le API una a una. In un'API di Tabella, il grant copre tutte le operazioni attive — l'elenco mostra "dà accesso a: getContas, addContas, …" perché tu sappia esattamente che cosa concedi.
  5. Premi Genera chiave API.

Il modale di creazione di una chiave API, con l'ambito per app ed endpoint.
Il modale di creazione di una chiave API, con l'ambito per app ed endpoint.

Copiare e conservare la chiave

Dopo la generazione, la finestra mostra la Chiave in chiaro — una sola volta. Copiala con Copia e conservala in un posto sicuro (un gestore di segreti, la cassaforte della tua squadra). Quando chiuderai la finestra non la vedrai più — la piattaforma non conserva la chiave in chiaro; se la perdi, potrai solo revocarla e generarne un'altra.

La chiave generata, in chiaro per l'unica volta, con il pulsante Copia.
La chiave generata, in chiaro per l'unica volta, con il pulsante Copia.

Atenção

Tratta la chiave come una password: non metterla nel codice sorgente, né negli URL, né in schermate utente. Se sospetti una fuga, revocala subito — generare una chiave nuova costa secondi.

Usare la chiave

La chiave viaggia nell'header x-api-key di ogni richiesta all'endpoint GraphQL dell' app:

curl -X POST 'https://o-teu-host/api/graphql/gestao-clientes' \
  -H 'content-type: application/json' \
  -H 'x-api-key: amk_………' \
  -d '{"query":"query { getContas(take: 5) { id nome } }"}'

La scheda Docs di ogni API genera questo esempio (e la variante JavaScript) già con l'operazione giusta — manca solo la tua chiave.

Che cosa una chiave vede e non vede:

  • Solo le API pubblicate — le bozze mai, nemmeno con l'ambito dell'app intera.
  • Solo ciò che l'ambito concede: chiamare un'app fuori dall'ambito restituisce 403 — API key not authorised for this project; chiamare un endpoint fuori dall'ambito, 403 — API key not authorised for this endpoint.
  • Sempre la versione principale dell'app (o la versione pubblicata dell' indirizzo usato) — mai la versione di lavoro di un developer.

Limiti ed errori

Ogni chiave ha un tetto di richieste al minuto. Le risposte di errore che un'integrazione deve saper trattare:

Risposta Significato Che cosa fare
401 Chiave mancante, non valida, scaduta o revocata. Verifica l'header e lo stato della chiave nell'elenco.
403 Chiave valida ma senza accesso all'app o all'endpoint. Regola l'ambito — genera una chiave nuova con l'ambito giusto.
429 Tetto di richieste al minuto raggiunto. Aspetta il tempo indicato nell'header retry-after e riprova.

Revocare una chiave

  1. Nell'elenco, premi l'icona di revoca della riga.
  2. Conferma con Revoca chiave.

La revoca è immediata: tutte le app che consumano questa chiave perdono l'accesso alla richiesta successiva. Una chiave revocata non può essere riattivata — resta nell'elenco, contrassegnata come revocata, come traccia.

Perché no…?

  • Ho perso la chiave — posso rivederla? No. La chiave in chiaro viene mostrata solo al momento della creazione. Revoca la vecchia e generane un'altra.
  • Devo dare accesso a un altro endpoint — modifico la chiave? L'ambito si definisce alla creazione. Genera una chiave nuova con l'ambito completo, sostituiscila nell'integrazione e revoca la vecchia.
  • Perché l'integrazione riceve 403 su un endpoint nuovo? La chiave è stata ristretta a endpoint specifici e il nuovo non è nell'elenco — lo stesso rimedio: chiave nuova con l'ambito giusto.
  • La chiave dà accesso alle schermate dell'app? No. Una chiave parla solo con l' endpoint GraphQL. Gli account degli utenti dell'app sono un'altra cosa, gestiti nelle impostazioni dell'app stessa.