Autenticazione
Ogni chiamata all’API Oblic usa una chiave creata nelle impostazioni di Oblic con un ruolo e gli ambiti necessari. La chiave può essere limitata agli indirizzi nella lista IP consentiti dell’organizzazione. API v2 usa invece token di accesso OAuth.
Creare una chiave
In Oblic, crea le chiavi in Impostazioni → Integrazione API. Assegna un nome, un ruolo (Owner, Admin o User) e gli ambiti di accesso necessari all’applicazione. La chiave viene mostrata una sola volta, alla creazione: conservala in un gestore di segreti o in una variabile d’ambiente protetta. Una chiave persa non può essere mostrata di nuovo: creane un’altra, poi elimina quella persa.
Inviare la chiave
Invia la chiave nell’intestazione Authorization, come Bearer, uno spazio e la chiave:
Chiamata con una chiave
curl https://api.oblic.app/external/v1/key \
-H 'Authorization: Bearer YOUR_API_KEY'
L’API è destinata ai server: non risponde alle richieste cross-origin dei browser. La chiave non deve quindi trovarsi in una pagina web o in un’app, dove chiunque potrebbe leggerla.
Ambiti di accesso
Una chiave mantiene gli ambiti assegnati alla creazione; ogni rotta elenca quelli accettati. Basta possederne uno per chiamarla. Una chiave creata prima dell’introduzione degli ambiti li possiede tutti tranne events:write, che registra gli eventi dei contatti: per inviarli, crea una chiave con questo ambito.
| Ambito | Permette alla chiave di |
|---|---|
email:send | Inviare email e leggere i modelli e le identità mittente usati |
sms:send | Inviare SMS e leggere l’account SMS, le intestazioni e i modelli |
whatsapp:send | Inviare messaggi WhatsApp e leggere numero, modelli e destinatari |
messages:read | Elencare i messaggi, leggerne gli esiti e consultare il riepilogo del report |
templates:manage | Gestire modelli email, intestazioni e modelli SMS, numero e modelli WhatsApp |
identities:manage | Gestire le identità mittente |
contacts:manage | Creare ed elencare liste di contatti e aggiungervi contatti |
events:write | Registrare eventi dei contatti, come gli ordini (vedi Eventi) |
webhooks:manage | Gestire webhook e consegne fallite |
accounts:manage | Gestire sottoaccount |
mcp:read e mcp:write servono al server MCP di Oblic, non a questa API. Gli endpoint elencano gli ambiti richiesti da ciascuna rotta, così come il documento OpenAPI, in x-oblic-scopes.
Ruoli
Il ruolo della chiave stabilisce le rotte accessibili, indipendentemente dagli ambiti:
- Le chiavi Owner e Admin possono chiamare ogni rotta.
- Le chiavi User possono chiamare tutte le rotte tranne quelle che modificano modelli, intestazioni SMS o numero WhatsApp, gestiscono webhook o sottoaccount, oppure controllano
/external/v1/health. Una chiave User non può essere creata contemplates:manage,webhooks:manageoaccounts:manage; una che possiede tutti gli ambiti, come una chiave precedente agli ambiti o di un sottoaccount, li elenca ma non può usarli.
Una chiave User su tali rotte riceve 403 INSUFFICIENT_SCOPE se non possiede nessuno degli ambiti richiesti, oppure 403 ROLE_NOT_ALLOWED su /external/v1/health, che non richiede ambiti, e quando possiede tutti gli ambiti.
Lista IP consentiti
In Impostazioni → Integrazione API → IP consentiti, elenca gli indirizzi da cui chiamano i server: singoli IPv4 o IPv6, oppure intervalli come 203.0.113.0/24. Finché la lista è vuota, la chiave funziona da qualsiasi indirizzo; quando contiene un elemento, funziona solo dagli indirizzi elencati. Le modifiche si applicano entro un minuto.
Una richiesta da altrove riceve 403 IP_NOT_ALLOWED; il messaggio indica l’indirizzo visto da Oblic, da aggiungere alla lista. Una richiesta per un sottoaccount è soggetta alla lista dell’organizzazione.
Verificare una chiave
Ogni chiave può leggere i propri dati: nome, ruolo, ambiti e operazioni attualmente disponibili.
Risposta parziale
{
"status": "success",
"data": {
"name": "Order service",
"role": "USER",
"scopes": ["email:send", "messages:read"],
"allScopes": false,
"organizationId": "ORG000R7ZM4Q2VXH00",
"capabilities": {
"scopes": [
{ "scope": "email:send", "action": "send email", "ownerOnly": false, "granted": true, "ready": true }
],
"verifiedSenders": [{ "identity": "example.com", "type": "Domain", "status": "verified" }],
"unverifiedSenders": [],
"defaultSender": "hello@example.com",
"allowedIps": ["203.0.113.0/24"],
"subAccount": false
}
},
"errors": null
}
Per ogni ambito, capabilities indica se la chiave può usarlo (granted) e se l’organizzazione è pronta (ready), ad esempio con un mittente verificato per inviare email; reason spiega un eventuale impedimento.
Richieste rifiutate
| Stato | cd | Quando |
|---|---|---|
| 401 | MISSING_API_KEY | Manca l’intestazione Authorization: Bearer |
| 401 | INVALID_API_KEY | Chiave sconosciuta a Oblic: errata o eliminata |
| 403 | IP_NOT_ALLOWED | Chiave valida da un indirizzo non incluso nella lista IP |
| 403 | INSUFFICIENT_SCOPE | La chiave non possiede gli ambiti della rotta; messaggio e intestazione WWW-Authenticate li elencano |
| 403 | ROLE_NOT_ALLOWED | Chiave User su /external/v1/health, oppure con tutti gli ambiti su una rotta riservata a Owner o Admin |
| 404 | ACCOUNT_NOT_FOUND | X-Oblic-On-Behalf-Of non identifica un sottoaccount attivo |
| 503 | AUTHENTICATION_UNAVAILABLE | Oblic non ha potuto verificare la chiave; non è stata eseguita alcuna operazione, riprova |
Proteggere le chiavi
- Una chiave per applicazione e ambiente, con i soli ambiti necessari: una perdita ha effetti limitati ed eliminarla interrompe una sola applicazione.
- Conserva le chiavi sui server, non nel codice, nei log o in contenuti scaricati da browser e app.
- Ruota le chiavi creando quella nuova, distribuendola e poi eliminando la vecchia. Una chiave eliminata smette subito di funzionare.