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.

AmbitoPermette alla chiave di
email:sendInviare email e leggere i modelli e le identità mittente usati
sms:sendInviare SMS e leggere l’account SMS, le intestazioni e i modelli
whatsapp:sendInviare messaggi WhatsApp e leggere numero, modelli e destinatari
messages:readElencare i messaggi, leggerne gli esiti e consultare il riepilogo del report
templates:manageGestire modelli email, intestazioni e modelli SMS, numero e modelli WhatsApp
identities:manageGestire le identità mittente
contacts:manageCreare ed elencare liste di contatti e aggiungervi contatti
events:writeRegistrare eventi dei contatti, come gli ordini (vedi Eventi)
webhooks:manageGestire webhook e consegne fallite
accounts:manageGestire 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 con templates:manage, webhooks:manage o accounts: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.

GET/external/v1/key

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

StatocdQuando
401MISSING_API_KEYManca l’intestazione Authorization: Bearer
401INVALID_API_KEYChiave sconosciuta a Oblic: errata o eliminata
403IP_NOT_ALLOWEDChiave valida da un indirizzo non incluso nella lista IP
403INSUFFICIENT_SCOPELa chiave non possiede gli ambiti della rotta; messaggio e intestazione WWW-Authenticate li elencano
403ROLE_NOT_ALLOWEDChiave User su /external/v1/health, oppure con tutti gli ambiti su una rotta riservata a Owner o Admin
404ACCOUNT_NOT_FOUNDX-Oblic-On-Behalf-Of non identifica un sottoaccount attivo
503AUTHENTICATION_UNAVAILABLEOblic 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.
Questa pagina è stata utile?