Creare e gestire le chiavi API in Simbase

Una chiave API autentica le tue richieste all'API di Simbase. Ogni chiave riceve alla creazione un insieme di permessi, che da quel momento restano fissi. Una chiave può servire più integrazioni, ma una chiave per integrazione è la scelta più sicura. Crei e gestisci le chiavi nella dashboard, in Integrations → API.

Creare una chiave API

Accedi a dashboard.simbase.com.
Vai su Integrations → API.
Clicca su Create New API Key.
Dai alla chiave un nome che dica a cosa serve, per esempio Usage Guard Toolkit. Il nome è solo un'etichetta. Compare nel tuo elenco di chiavi e da nessun'altra parte.
In Resources, imposta i permessi di cui la chiave ha bisogno. Vedi Permessi più sotto.
Clicca su Create API Key, poi copia la chiave.

Copia subito la chiaveSimbase mostra la chiave una sola volta, nella finestra "Keep your key safe". Clicca sulla chiave per copiarla, poi salvala in un password manager o nell'archivio dei secret della tua piattaforma. Se la perdi, non puoi più vederla. Elimina la chiave e creane una nuova.

Guarda la demo qui sotto per le istruzioni passo passo:

Permessi

I permessi si impostano per risorsa, su uno di tre livelli. None significa che la chiave non può accedere a quella risorsa. È il valore predefinito su ogni riga. Read legge i dati senza modificare nulla. Write crea, modifica ed elimina. Selezionando Write si seleziona anche Read sulla stessa riga, perché tutto ciò che scrive deve prima leggere.

Non tutte le risorse offrono tutti e tre i livelli. Account e Usage sono in sola lettura, quindi mostrano None e Read. SIM card state, Reset, Registration e Auto-disable sono azioni, non dati, quindi mostrano None e Write.

L'albero delle risorse

Risorsa	Livelli	Comprende
All resources	None, Read, Write	Tutte le righe sottostanti insieme
Account	None, Read	I dati del tuo account: organizzazione, utenti e ruoli, saldo
Usage	None, Read	Dati di utilizzo: cronologia di dati, SMS e sessioni
SIM cards	None, Read, Write	Tutto il gruppo SIM cards sottostante
– SIM card details	None, Read, Write	Il record della SIM: etichetta, Tags, piano di copertura, IP pubblico, limiti di utilizzo e blocco IMEI
– SIM card state	None, Write	Attivare e disattivare le SIM
– Reset	None, Write	Reset della connessione: chiude la sessione dati corrente così che se ne possa aprire una nuova
– SMS	None, Read, Write	Leggere la cronologia dei messaggi e inviare messaggi
– Registration	None, Write	Registrare nuove SIM sull'account
– Auto-disable	None, Write	Impostare e cancellare la data di Auto-disable
Utilities	None, Read	Tutto il gruppo Utilities sottostante
– Geo	None, Read	Ricerche Cell ID: la cella a cui è agganciata una SIM
Integrations	None, Read, Write	Tutto il gruppo Integrations sottostante
– Webhooks	None, Read, Write	Elencare, creare ed eliminare gli endpoint dei webhook

Risorsa

All resources
Account
Usage
SIM cards
– SIM card details
– SIM card state
– Reset
– SMS
– Registration
– Auto-disable
Utilities
– Geo
Integrations
– Webhooks

Righe principali e secondarie

Accanto a SIM cards, Utilities e Integrations c'è una freccia. Cliccaci sopra per espandere i singoli permessi sottostanti.

Impostare un livello su una riga principale lo applica a ogni riga secondaria, oppure applica il livello più alto che quella riga offre. Se imposti All resources su Write, Account e Usage ricevono Read, perché è il massimo che supportano.
Se imposti solo una riga secondaria, la riga principale non mostra alcuna selezione. È normale. Una riga principale mostra un livello solo quando tutte le sue righe secondarie coincidono.

Scegliere un livello

Concedi il minimo indispensabile all'integrazione. Una chiave che può solo leggere l'utilizzo non può disattivare una SIM se finisce nelle mani sbagliate.

L'integrazione…	Imposta
Genera report sul consumo dati	Usage: Read e SIM card details: Read
Disattiva le SIM alla fine di un pacchetto dati	SIM card state: Write
Attiva la protezione antifurto o la disattiva	SIM card details: Write
Inoltra o invia SMS	SMS: Write
Registra nuove SIM	Registration: Write
Esegue il Usage Guard Toolkit	All resources: Write

L'integrazione…

Genera report sul consumo dati
Disattiva le SIM alla fine di un pacchetto dati
Attiva la protezione antifurto o la disattiva
Inoltra o invia SMS
Registra nuove SIM
Esegue il Usage Guard Toolkit

Nel riferimento API compaiono come nomi di scope costruiti sullo stesso albero. SIM card details corrisponde a simcards.details:read e simcards.details:write.

Impostazioni avanzate

Attiva Show advanced settings per due campi facoltativi. Puoi lasciarli entrambi vuoti.

IP restrictions

Limita la chiave a un solo indirizzo IP affidabile o a un intervallo in notazione CIDR. Le richieste da qualsiasi altro indirizzo vengono rifiutate. Lascia il campo vuoto per nessuna limitazione. L'elenco delle chiavi mostra allora 0.0.0.0/0 sotto Allowed IPs, cioè qualsiasi indirizzo.

Solo indirizzi fissiUsa una limitazione IP quando l'integrazione gira da un indirizzo fisso, come il tuo server o un gateway NAT. Le piattaforme di automazione in hosting come Make.com e Zapier chiamano da un pool di indirizzi che cambia, quindi limitare la chiave per IP le blocca.

Expires in (number of days)

Il numero di giorni dalla creazione fino a quando la chiave smette di funzionare. Inserisci 31 e la chiave scade tra 31 giorni. Lascia il campo vuoto e la chiave non scade mai.

Le chiavi a breve durata sono utili per migrazioni una tantum, accessi per collaboratori esterni e tutto ciò che altrimenti dovresti ricordarti di revocare.

Gestire le chiavi

L'elenco API mostra tutte le chiavi dell'account: nome, Key ID troncato, livello di permessi con cui è stata creata, ultimo utilizzo e limitazione IP. Last API call è mostrato nel fuso orario dell'account, e Allowed IPs mostra 0.0.0.0/0 quando non c'è alcuna limitazione.

Il Key ID serve solo a distinguere le chiavi. È troncato e non può essere usato per l'autenticazione.

I permessi si fissano alla creazione e non si possono modificare in seguito. Per cambiare cosa può fare una chiave, creane una nuova con i permessi giusti, sposta l'integrazione sulla nuova chiave ed elimina quella vecchia.

Il menu a tre puntini alla fine di ogni riga ha una sola opzione: Delete. Una chiave eliminata smette subito di funzionare e le richieste che la usano non superano l'autenticazione.

Usare la chiave

Invia la chiave come bearer token in ogni richiesta:

Richiesta

GET /v2/simcards HTTP/1.1
Host: api.simbase.com
Authorization: Bearer YOUR_API_KEY

La documentazione completa degli endpoint è su developer.simbase.com.

Domande frequenti

No. I permessi si impostano alla creazione e restano fissi. Crea una chiave sostitutiva con i permessi che ti servono, sposta l'integrazione e poi elimina la vecchia chiave.

No. La chiave completa viene mostrata una sola volta, alla creazione. L'elenco mostra solo un Key ID troncato, che non serve per l'autenticazione. Elimina la chiave e creane una nuova.

Che la chiave non ha limitazioni IP e accetta richieste da qualsiasi indirizzo. È ciò che ottieni lasciando vuoto il campo IP restrictions.

Nulla ti impedisce di usare la stessa chiave per più integrazioni, ma una chiave per integrazione vale il minuto in più. Puoi limitare ciascuna a ciò che le serve, vedere dalla colonna Last API call quale è ancora in uso, ed eliminarne o rinnovarne una senza bloccare le altre. Una chiave condivisa deve avere i permessi di tutti messi insieme, e revocarla ferma tutto in un colpo.