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.
| Escopo | Permite à chave |
|---|---|
email:send | Enviar e-mails e ler os modelos e identidades de remetente usados |
sms:send | Enviar SMS e ler conta, cabeçalhos e modelos de SMS |
whatsapp:send | Enviar mensagens WhatsApp e ler número, modelos e destinatários |
messages:read | Listar mensagens, consultar seus resultados e ler o resumo do relatório |
templates:manage | Gerenciar modelos de e-mail, cabeçalhos e modelos de SMS, número e modelos WhatsApp |
identities:manage | Gerenciar identidades de remetente |
contacts:manage | Criar e listar listas de contatos e adicionar contatos |
events:write | Registrar eventos dos contatos, como pedidos (veja Eventos) |
webhooks:manage | Gerenciar webhooks e entregas com falha |
accounts:manage | Gerenciar 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 comtemplates:manage,webhooks:manageouaccounts: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.
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
| Status | cd | Quando |
|---|---|---|
| 401 | MISSING_API_KEY | Ausência do cabeçalho Authorization: Bearer |
| 401 | INVALID_API_KEY | Chave desconhecida de Oblic: digitada incorretamente ou excluída |
| 403 | IP_NOT_ALLOWED | Chave válida de endereço fora da lista permitida |
| 403 | INSUFFICIENT_SCOPE | A chave não tem nenhum escopo da rota; mensagem e cabeçalho WWW-Authenticate os informam |
| 403 | ROLE_NOT_ALLOWED | Chave User em /external/v1/health, ou com todos os escopos numa rota reservada a Owner ou Admin |
| 404 | ACCOUNT_NOT_FOUND | X-Oblic-On-Behalf-Of não identifica uma subconta ativa |
| 503 | AUTHENTICATION_UNAVAILABLE | Oblic 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.