MoraselL’API Morasel per sviluppatori
Leggi e agisci sugli stessi record che usa il tuo team — conversazioni, clienti, appuntamenti, ordini — con token di cui definisci l’ambito, limiti per IP e fai scadere secondo i tuoi tempi.
Perché una chiave senza ambito né scadenza è un rischio
Un’unica chiave API senza ambito, senza restrizione IP e senza scadenza è un rischio permanente: se trapela, chi la trova può leggere o scrivere tutto ciò che lo spazio di lavoro consente. La maggior parte delle integrazioni ha bisogno solo di una frazione di quell’accesso, per un periodo fisso, da sistemi noti.
- Un token con accesso completo può leggere o scrivere record che un’integrazione non ha mai richiesto.
- Un token senza scadenza resta valido un anno dopo la fine del progetto che lo ha creato.
- Un token utilizzabile da qualsiasi IP può essere riutilizzato da ovunque ne trapeli il testo in chiaro.
- Una chiave di cui nessuno può più recuperare il testo in chiaro non si può verificare, solo revocare e sostituire.
Cosa registra Morasel per ogni token
Un record di token per integrazione, così un titolare vede cosa può fare e quando è stato usato l’ultima volta senza chiederlo al team che lo ha creato.
- Nome del token
- L’etichetta che il tuo team dà al token, collegata all’integrazione a cui appartiene.
- Prefisso
- I primi caratteri del token, mostrati dopo la creazione per identificarlo senza il segreto.
- Ambiti
- Gli oggetti e le azioni raggiungibili dal token; lettura di default, scrittura concessa per oggetto.
- Lista IP consentite
- Fino a 20 indirizzi da cui il token può essere usato; vuota significa nessuna restrizione IP.
- Scadenza
- Una data fino a 365 giorni dopo la quale il token smette di funzionare.
- Ultimo utilizzo
- L’ora più recente in cui una richiesta si è autenticata con questo token.
- Endpoint webhook
- L’URL e il segreto di firma che registri dallo spazio di lavoro per la tua integrazione.
Dalla creazione di un token alla sua rotazione
Il segreto in chiaro esiste una sola volta, alla creazione. Tutto il resto funziona sul prefisso e sugli ambiti che hai impostato.
Crea un token (titolare)
Assegna un nome, scegli gli ambiti, e imposta facoltativamente una lista IP consentite e una scadenza fino a 365 giorni.
Copia il segreto una volta
Il token completo viene mostrato una sola volta. Dopo, solo il suo prefisso resta visibile sul record.
Chiama la REST API con un header Bearer
Autentica le richieste verso gli endpoint documentati; ogni chiamata è verificata rispetto agli ambiti e alla lista IP del token.
Registra un endpoint webhook e conserva il suo segreto di firma
Aggiungi l’URL dell’endpoint dallo spazio di lavoro e conserva il segreto di firma fornito.
Ruota: crea il successore, revoca il vecchio
Emetti un nuovo token prima che il vecchio scada o sia compromesso, poi revoca il vecchio una volta attivo il nuovo.
Cosa vede il cliente
Un messaggio inviato tramite l’API appare esattamente come uno inviato dallo spazio di lavoro — il cliente non ha modo di distinguerli.
Cosa vede il tuo team
L’attività di un token è un record, non un mistero nei log.
- Gli ambiti, la lista IP, la scadenza e l’ultimo utilizzo di ogni token, su un solo record.
- L’endpoint webhook e l’opzione di rivelare o ruotare il suo segreto di firma.
- Un prefisso per identificare un token in una conversazione senza dover più usare il segreto.
- Eventi di creazione e revoca nello stesso registro di controllo di tutto il resto dello spazio di lavoro.
Chi può fare cosa
Emettere e revocare l’accesso resta riservato a chi possiede lo spazio di lavoro, e ogni modifica viene registrata.
- Solo un titolare dello spazio di lavoro può creare o revocare un token API.
- Gli ambiti sono di sola lettura per default; l’accesso in scrittura a un oggetto è concesso esplicitamente, mai presunto.
- Una lista IP consentite, quando impostata, limita un token a fino a 20 indirizzi noti.
- Ogni creazione e revoca di token finisce nel registro di controllo, con chi l’ha fatto e quando.
Cosa non fa Morasel
Gli endpoint webhook si registrano con un segreto di firma dallo spazio di lavoro. Morasel non pubblica SDK; la REST API è documentata come OpenAPI. La registrazione di un endpoint ne conserva l’URL e il segreto di firma per la tua integrazione.
Inizia a costruire su Morasel
Crea uno spazio di lavoro, emetti un token con ambito definito, e leggi il riferimento OpenAPI degli endpoint di cui hai bisogno.
Domande degli sviluppatori
Come ottengo un token?
Un titolare dello spazio di lavoro lo crea da lì: nome, ambiti, e facoltativamente una lista IP consentite e una scadenza. Il testo in chiaro viene mostrato una volta alla creazione.
Quali ambiti esistono?
L’accesso in lettura è quello di default. L’accesso in scrittura a un oggetto specifico — conversazioni, clienti, appuntamenti, ordini — è concesso per ambito, così un token raggiunge solo ciò per cui è stato creato.
Cosa fa la lista IP consentite?
Limita il token a fino a 20 indirizzi IP specifici. Lasciala vuota e il token funziona da ovunque venga usato il segreto; impostala e le richieste da altri indirizzi vengono rifiutate.
Quanto può durare un token?
Fino a 365 giorni. Dopo, o alla data che imposti, smette di autenticare e va sostituito.
Dove si trova il riferimento API?
La REST API è documentata come OpenAPI su /docs, coprendo gli endpoint raggiungibili dagli ambiti di un token.