Autenticação

Cada chamada à API Oblic leva uma chave criada nas configurações de Oblic com uma função e os escopos necessários. A chave pode ficar restrita à lista de IPs permitidos da organização. API v2 usa tokens de acesso OAuth em vez de chaves.

Criar uma chave

Crie chaves em Configurações → Integração de API no Oblic. Defina nome, função (Owner, Admin ou User) e os escopos exigidos pela aplicação. A chave aparece uma única vez, na criação: guarde-a num gerenciador de segredos ou variável de ambiente protegida. Uma chave perdida não pode ser exibida novamente; crie outra e exclua a perdida.

Enviar a chave

Envie a chave no cabeçalho Authorization, como Bearer, um espaço e a chave:

Chamada com uma chave

curl https://api.oblic.app/external/v1/key \
  -H 'Authorization: Bearer YOUR_API_KEY'

A API é para servidores: não atende solicitações de origem cruzada de navegadores. Portanto, a chave nunca precisa estar numa página ou aplicativo onde qualquer pessoa possa lê-la.

Escopos

A chave mantém os escopos atribuídos na criação; cada rota lista os que aceita. Ter qualquer um deles permite chamá-la. Chaves anteriores aos escopos têm todos, exceto events:write, que registra eventos dos contatos: para enviá-los, crie uma chave com esse escopo.

EscopoPermite à chave
email:sendEnviar e-mails e ler os modelos e identidades de remetente usados
sms:sendEnviar SMS e ler conta, cabeçalhos e modelos de SMS
whatsapp:sendEnviar mensagens WhatsApp e ler número, modelos e destinatários
messages:readListar mensagens, consultar seus resultados e ler o resumo do relatório
templates:manageGerenciar modelos de e-mail, cabeçalhos e modelos de SMS, número e modelos WhatsApp
identities:manageGerenciar identidades de remetente
contacts:manageCriar e listar listas de contatos e adicionar contatos
events:writeRegistrar eventos dos contatos, como pedidos (veja Eventos)
webhooks:manageGerenciar webhooks e entregas com falha
accounts:manageGerenciar subcontas

mcp:read e mcp:write destinam-se ao servidor MCP de Oblic, não a esta API. Os endpoints listam os escopos de cada rota, assim como o documento OpenAPI, em x-oblic-scopes.

Funções

A função da chave determina quais rotas ela pode chamar, independentemente dos escopos:

  • Chaves Owner e Admin podem chamar todas as rotas.
  • Chaves User podem chamar todas, exceto as que alteram modelos, cabeçalhos de SMS ou número WhatsApp, gerenciam webhooks ou subcontas, ou verificam /external/v1/health. Não se cria uma chave User com templates:manage, webhooks:manage ou accounts:manage; uma chave com todos os escopos, como as antigas ou de subconta, os lista, mas não pode usá-los.

Nessas rotas, uma chave User recebe 403 INSUFFICIENT_SCOPE por não ter nenhum dos escopos exigidos, ou 403 ROLE_NOT_ALLOWED em /external/v1/health, que não exige escopo, e quando tem todos os escopos.

Lista de IPs permitidos

Em Configurações → Integração de API → IPs permitidos, liste os endereços de origem dos servidores: IPv4 ou IPv6 individuais ou intervalos como 203.0.113.0/24. Com a lista vazia, a chave funciona de qualquer endereço; após incluir um, funciona apenas nos endereços listados. Alterações entram em vigor em até um minuto.

Uma solicitação de outro endereço recebe 403 IP_NOT_ALLOWED; a mensagem informa o endereço visto por Oblic, que deve ser adicionado. Solicitações por uma subconta seguem a lista da organização.

GET/external/v1/key

Verificar uma chave

Qualquer chave pode consultar seus próprios dados: nome, função, escopos e o que pode fazer agora.

Parte da resposta

{
  "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
}

Para cada escopo, capabilities informa se a chave pode usá-lo (granted) e se a organização está preparada (ready), como ter remetente verificado para enviar e-mail; reason explica por que não.

Pedidos recusados

StatuscdQuando
401MISSING_API_KEYAusência do cabeçalho Authorization: Bearer
401INVALID_API_KEYChave desconhecida de Oblic: digitada incorretamente ou excluída
403IP_NOT_ALLOWEDChave válida de endereço fora da lista permitida
403INSUFFICIENT_SCOPEA chave não tem nenhum escopo da rota; mensagem e cabeçalho WWW-Authenticate os informam
403ROLE_NOT_ALLOWEDChave User em /external/v1/health, ou com todos os escopos numa rota reservada a Owner ou Admin
404ACCOUNT_NOT_FOUNDX-Oblic-On-Behalf-Of não identifica uma subconta ativa
503AUTHENTICATION_UNAVAILABLEOblic não conseguiu verificar a chave; nada foi feito, tente novamente

Proteger as chaves

  • Uma chave por aplicação e ambiente, apenas com os escopos necessários: um vazamento tem impacto limitado e a exclusão interrompe só aquela aplicação.
  • Mantenha as chaves nos servidores, fora do código, logs e qualquer conteúdo baixado por navegador ou aplicativo.
  • Faça a rotação criando e implantando a chave nova, depois excluindo a antiga. A chave excluída para de funcionar imediatamente.
Esta página foi útil?