Sottoaccount
Una piattaforma che invia per i propri clienti assegna a ciascuno un sottoaccount: un'organizzazione Oblic distinta, con mittenti, modelli, messaggi e report propri. La tua chiave agisce per suo conto indicandola. La gestione dei sottoaccount richiede una chiave Owner o Admin con accounts:manage.
Creare un sottoaccount
- Nome
name- Tipo
- string
- Descrizione
Obbligatorio: il nome del cliente, fino a 511 caratteri.
- Nome
externalId- Tipo
- string
- Descrizione
Obbligatorio: il tuo identificativo del cliente, fino a 100 lettere ASCII, cifre e caratteri
_,.,:e-. Serve a indicare il sottoaccount in seguito.
- Nome
issueKey- Tipo
- boolean
- Descrizione
Indica se emettere una chiave API propria per il sottoaccount; il valore predefinito è
true.
Creare un sottoaccount
curl -X POST https://api.oblic.app/external/v1/accounts \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{ "name": "Asha Textiles", "externalId": "tenant-4821" }'
Risposta
{
"status": "success",
"data": {
"id": "ORG000R7ZM4Q2VXH00",
"name": "Asha Textiles",
"externalId": "tenant-4821",
"active": true,
"createdAt": "2026-10-24T09:30:00Z",
"apiKey": "obl_live_…"
},
"errors": null
}
apiKeyappare solo in questa risposta: conservala subito oppure crea nuovamente il sottoaccount per ottenerne un'altra. È una chiave User con gli ambiti predefiniti precedenti, che escludonoevents:write: consente invio, lettura e gestione di identità ed elenchi di contatti, ma non l'accesso alle route che richiedono una chiave Owner o Admin.- Ripetere lo stesso
externalIdrestituisce quel sottoaccount, riattivato se era disattivato e con il nome invariato. Ogni chiamata emette un'altra chiave, salvo quandoissueKeyèfalse. Le chiavi precedenti restano valide, tranne quelle revocate alla disattivazione. - Un sottoaccount non ha sottoaccount: crearne uno mentre si agisce per conto di un sottoaccount restituisce
403 SUB_ACCOUNT_NOT_ALLOWED.
Elencare i sottoaccount
Tutti i sottoaccount, anche quelli disattivati con active a false, nell'ordine di creazione. L'elenco non contiene mai chiavi.
Disattivare un sottoaccount
Disattiva il sottoaccount tramite il suo id Oblic, non il tuo externalId, e revoca subito tutte le sue chiavi. Crearlo di nuovo con il suo externalId lo riattiva. Un sottoaccount non appartenente all'organizzazione restituisce 404 ACCOUNT_NOT_FOUND.
Agire per conto di un sottoaccount
Invia X-Oblic-On-Behalf-Of con l'externalId del sottoaccount: la richiesta viene eseguita per suo conto, come con la sua chiave. Una sola chiave serve per tutti i clienti, senza conservarne una per ciascuno.
Inviare dall'account di un cliente
curl -X POST https://api.oblic.app/external/v1/messages/email \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'X-Oblic-On-Behalf-Of: tenant-4821' \
-H 'Content-Type: application/json' \
-d '{ "from": "hello@ashatextiles.example", "to": ["asha@example.org"], "subject": "Welcome", "html": "<p>Welcome!</p>" }'
- Del sottoaccount: le email partono solo dalle sue identità; messaggi, report, modelli, webhook e valori
Idempotency-Keysono propri del sottoaccount. - Della tua organizzazione: il tuo portafoglio paga i suoi messaggi e la tua lista di IP consentiti si applica alle richieste eseguite per suo conto.
- Si applica il ruolo della tua chiave: gestisci quindi modelli, webhook o numero WhatsApp del cliente con la tua chiave Owner o Admin e l'intestazione.
- Un
externalIdsenza sottoaccount attivo restituisce404 ACCOUNT_NOT_FOUND. - Gli eventi webhook del sottoaccount arrivano ai suoi endpoint se ne ha, altrimenti ai tuoi, con il suo
externalIdnell'accountdi ogni evento. Vedi Webhooks. - I modelli SMS inviati da un sottoaccount sono quelli che condividi con esso. Vedi Modelli.