Chiavi API

Una API key è la credenziale che identifica il tuo account e ti permette di chiamare l'API Sterna. Questa pagina spiega cosa contiene una chiave, dove la ottieni, come riconoscerla e come proteggerla. Per il formato dell'header HTTP e per la distinzione fra ambienti test/live e permessi (scopes), vedi la pagina "Autenticazione".

Una chiave è prefisso + corpo opaco; il prefisso indica l'ambiente, e dalla chiave l'API ricava account, ambiente e permessi.

Come si creano le chiavi

Le chiavi API si creano dal pannello Sterna, non via API. Non esiste un endpoint per generare, modificare o revocare una chiave dalla tua piattaforma: tutte queste operazioni sono volutamente riservate all'interfaccia di amministrazione.

Quando ti serve una nuova chiave — per esempio per separare due integrazioni, o per ruotare una chiave usata da tempo — la generi dal pannello e la incolli nel tuo sistema.

Quando crei una chiave dal pannello, il suo valore completo viene mostrato in chiaro una sola volta, al momento della creazione: dopo non è più recuperabile. Copialo e conservalo subito in un luogo sicuro. Se lo perdi, non puoi recuperarlo: dovrai revocare la chiave e generarne una nuova.

Anatomia di una chiave

Una chiave è una stringa unica composta da due parti: un prefisso che indica l'ambiente, e un corpo opaco generato casualmente. Esempio: stk_test_51H8d... — il prefisso stk_test_ dice subito che è una chiave di test.

Il prefisso è l'unica parte significativa per te: ti permette di riconoscere a colpo d'occhio in che ambiente sta operando un'integrazione. Il resto della stringa non ha significato semantico: è un identificatore casuale, non interpretarlo.

Per la distinzione completa fra chiavi test (stk_test_...) e chiavi live (stk_live_...) e per i loro scopes (read, write), vedi "Autenticazione".

Vedere i dati della tua chiave

La chiamata GET /v1/me risponde anche con un blocco api_key che descrive la chiave che hai usato: l'identificativo, l'ambiente e gli scopes attivi. È il modo più rapido per verificare con quale chiave stai parlando all'API. Per la chiamata completa vedi "Prima chiamata: identità".

{
  "api_key": {
    "id": "...",
    "environment": "test",
    "scopes": ["read", "write"]
  }
}

Se vedi environment: "live" mentre ti aspettavi test, stai per fare ordini reali: fermati e ricontrolla la chiave configurata nel tuo sistema.

Account che fanno parte di un gruppo

Se il tuo account fa parte di un gruppo (descritto in "Ordini in una rete"), la tua chiave viene generata dall'account principale dal pannello e ti viene consegnata. Dal tuo punto di vista la chiave si usa esattamente come una chiave normale: stesso header, stessi ambienti, stessi scopes.

L'unica differenza è organizzativa: la creazione non avviene nel tuo pannello ma in quello dell'account principale. Per il flusso completo degli ordini in un gruppo, vedi "Ordini in una rete".

Sicurezza della chiave

Una chiave API è una credenziale riservata: chi la possiede può operare a tuo nome, fino al limite del plafond e degli scopes della chiave. Trattala come una password.

Non condividerla via email, chat o canali non sicuri.
Non inserirla in codice pubblico, repository condivisi, log o pagine web visibili agli utenti finali.
Usala solo da codice server-side, mai nel browser o sui dispositivi dei tuoi clienti finali.
Usa chiavi diverse per integrazioni diverse: se ne compromette una sola, revochi solo quella senza interrompere il resto.
Ruota periodicamente le chiavi live, anche in assenza di incidenti.

Se sospetti che una chiave sia stata compromessa, revocala subito dal pannello e generane una nuova. Se non hai accesso al pannello, contatta il supporto Sterna.

Rotazione e ciclo di vita

Dal pannello puoi gestire una chiave esistente: rinominarla, rigenerarla, o revocarla. La revoca ha effetto immediato ed è irreversibile — una chiave revocata smette subito di funzionare e non può essere riattivata. Alla creazione puoi anche impostare una data di scadenza opzionale, oltre la quale la chiave smette automaticamente di funzionare.