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.


POST/external/v1/accounts

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
}
  • apiKey appare solo in questa risposta: conservala subito oppure crea nuovamente il sottoaccount per ottenerne un'altra. È una chiave User con gli ambiti predefiniti precedenti, che escludono events: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 externalId restituisce quel sottoaccount, riattivato se era disattivato e con il nome invariato. Ogni chiamata emette un'altra chiave, salvo quando issueKey è 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.

GET/external/v1/accounts

Elencare i sottoaccount

Tutti i sottoaccount, anche quelli disattivati con active a false, nell'ordine di creazione. L'elenco non contiene mai chiavi.


DELETE/external/v1/accounts/{accountId}

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-Key sono 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 externalId senza sottoaccount attivo restituisce 404 ACCOUNT_NOT_FOUND.
  • Gli eventi webhook del sottoaccount arrivano ai suoi endpoint se ne ha, altrimenti ai tuoi, con il suo externalId nell'account di ogni evento. Vedi Webhooks.
  • I modelli SMS inviati da un sottoaccount sono quelli che condividi con esso. Vedi Modelli.
Questa pagina è stata utile?