Autenticacao

Conceituacao

Toda requisicao ao Ogmma API precisa ser autenticada. A autenticacao garante que apenas usuarios e sistemas autorizados acessem os recursos da sua instituicao.

O Ogmma API oferece dois metodos de autenticacao:

• API Key -- Recomendado para integracoes server-to-server
• JWT (JSON Web Token) -- Usado pela interface web do Ogmma

Para integracoes via API, recomendamos fortemente o uso de API Keys por serem mais simples, nao expirarem (a menos que voce configure) e oferecerem controle granular de permissoes.

---

API Key

Como Funciona

API Keys sao chaves de acesso geradas pela plataforma que identificam sua aplicacao e instituicao. Cada chave possui escopos de permissao configuráveis, permitindo controle fino sobre o que a integracao pode fazer.

Formato da Chave

As API Keys seguem o formato:

oapi_sk_{ambiente}_{identificador_aleatorio}

Prefixo	Ambiente	Uso
oapi_sk_live_	Producao	Operacoes reais -- mensagens sao enviadas de verdade
oapi_sk_test_	Sandbox	Ambiente de teste -- mensagens sao simuladas

Exemplo:

oapi_sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
oapi_sk_test_x9y8z7w6v5u4t3s2r1q0p9o8n7m6l5k4

Como Usar

Envie a API Key no header Authorization de todas as requisicoes:

Authorization: Bearer oapi_sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Exemplo de Requisicao

curl -X GET "https://oapi.ogmma.com.br/v1/channels" \
  -H "Authorization: Bearer oapi_sk_live_a1b2c3d4e5f6..."

Criar uma API Key

Metodo

POST https://oapi.ogmma.com.br/v1/api-keys

Header

Key	Value
Authorization	Bearer {jwt-token}
Content-Type	application/json

Atributos

Obrigatorios

Atributos	Tipo	Descricao
name	string	Nome identificador da chave (3-100 caracteres)
permissions	string[]	Lista de permissoes da chave. Pelo menos uma permissao e obrigatoria.

Opcionais

Atributos	Tipo	Descricao
rateLimit	number	Limite de requisicoes por minuto (1-10000, padrao: 60)
expiresAt	string	Data de expiracao (ISO 8601). Se omitido, a chave nao expira.
environment	string	Ambiente da chave: live (padrao) ou test (sandbox).

Request Body

{
  "name": "Backend ERP",
  "permissions": [
    "messages.send",
    "messages.read",
    "contacts.read",
    "contacts.write",
    "conversations.read"
  ],
  "expiresAt": "2026-12-31T23:59:59.000Z"
}

Response

201 - Criado

{
  "id": "64f8b2c3e1a2b3c4d5e6f7b0",
  "name": "Backend ERP",
  "key": "oapi_sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "prefix": "oapi_sk_live",
  "permissions": [
    "messages.send",
    "messages.read",
    "contacts.read",
    "contacts.write",
    "conversations.read"
  ],
  "environment": "live",
  "expiresAt": "2026-12-31T23:59:59.000Z",
  "createdAt": "2025-01-15T10:30:00.000Z"
}

Atencao

A chave completa so e exibida uma unica vez na criacao. Guarde-a em local seguro (ex: variavel de ambiente, cofre de secrets). Apos isso, apenas o prefixo sera visivel na listagem.

Listar API Keys

Metodo

GET https://oapi.ogmma.com.br/v1/api-keys

Response

200 - OK

{
  "data": [
    {
      "id": "64f8b2c3e1a2b3c4d5e6f7b0",
      "name": "Backend ERP",
      "prefix": "oapi_sk_live_a1b2",
      "permissions": ["messages.send", "messages.read"],
      "environment": "live",
      "lastUsedAt": "2025-01-20T14:22:00.000Z",
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ]
}

Revogar API Key

Metodo

DELETE https://oapi.ogmma.com.br/v1/api-keys/{apiKeyId}

Response

204 - Sem Conteudo

A chave foi revogada com sucesso. Qualquer requisicao usando essa chave retornara 401 Unauthorized.

---

JWT (JSON Web Token)

Conceituacao

O JWT e utilizado pela interface web do Ogmma para autenticar usuarios. O fluxo utiliza uma autenticacao em duas etapas, ja que um usuario pode pertencer a multiplas instituicoes.

Fluxo de Autenticacao

1. POST /auth/login (email + senha)
   ↓
   Retorna token PENDENTE + lista de instituicoes
   ↓
2. POST /auth/select-institution (institutionId)
   ↓
   Retorna token COMPLETO (com institutionId)
   ↓
3. Usa token completo em todas as requisicoes

Etapa 1: Login

Metodo

POST https://oapi.ogmma.com.br/v1/auth/login

Header

Key	Value
Content-Type	application/json

Atributos

Obrigatorios

Atributos	Tipo	Descricao
email	string	Email do usuario
password	string	Senha do usuario

Request Body

{
  "email": "joao@minhaempresa.com.br",
  "password": "SenhaSegura123!"
}

Response

200 - OK (Multiplas Instituicoes)

Quando o usuario pertence a mais de uma instituicao, a API retorna um token pendente e a lista de instituicoes para selecao:

{
  "requiresInstitutionSelection": true,
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiI2NGY4YjJjM2UxYTJiM2M0ZDVlNmY3YTgiLCJlbWFpbCI6ImpvYW9AbWluaGFlbXByZXNhLmNvbS5iciJ9...",
  "institutions": [
    {
      "id": "64f8b2c3e1a2b3c4d5e6f7a9",
      "name": "Minha Empresa LTDA"
    },
    {
      "id": "64f8b2c3e1a2b3c4d5e6f7aa",
      "name": "Outra Empresa SA"
    }
  ]
}

200 - OK (Instituicao Unica)

Quando o usuario pertence a apenas uma instituicao, a API retorna diretamente o token completo:

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiI2NGY4YjJjM2UxYTJiM2M0ZDVlNmY3YTgiLCJlbWFpbCI6ImpvYW9AbWluaGFlbXByZXNhLmNvbS5iciIsImluc3RpdHV0aW9uSWQiOiI2NGY4YjJjM2UxYTJiM2M0ZDVlNmY3YTkifQ...",
  "user": {
    "id": "64f8b2c3e1a2b3c4d5e6f7a8",
    "name": "João Silva",
    "email": "joao@minhaempresa.com.br"
  }
}

401 - Credenciais Invalidas

{
  "error": "Email ou senha invalidos"
}

Etapa 2: Selecionar Instituicao

Necessario apenas quando o login retorna requiresInstitutionSelection: true.

Metodo

POST https://oapi.ogmma.com.br/v1/auth/select-institution

Header

Key	Value
Authorization	Bearer {token-pendente}
Content-Type	application/json

Atributos

Obrigatorios

Atributos	Tipo	Descricao
institutionId	string	ID da instituicao selecionada

Request Body

{
  "institutionId": "64f8b2c3e1a2b3c4d5e6f7a9"
}

Response

200 - OK

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiI2NGY4YjJjM2UxYTJiM2M0ZDVlNmY3YTgiLCJlbWFpbCI6ImpvYW9AbWluaGFlbXByZXNhLmNvbS5iciIsImluc3RpdHV0aW9uSWQiOiI2NGY4YjJjM2UxYTJiM2M0ZDVlNmY3YTkifQ...",
  "user": {
    "id": "64f8b2c3e1a2b3c4d5e6f7a8",
    "name": "João Silva",
    "email": "joao@minhaempresa.com.br"
  },
  "institution": {
    "id": "64f8b2c3e1a2b3c4d5e6f7a9",
    "name": "Minha Empresa LTDA"
  }
}

Payload do Token

O JWT completo contem as seguintes informacoes:

Campo	Tipo	Descricao
userId	string	ID do usuario
email	string	Email do usuario
institutionId	string	ID da instituicao selecionada
iat	number	Timestamp de emissao
exp	number	Timestamp de expiracao

Token Pendente vs Completo

• Token Pendente: Contem apenas userId e email. So permite chamar /auth/select-institution e /auth/institutions.
• Token Completo: Contem userId, email e institutionId. Permite acesso a todos os endpoints protegidos.

---

Escopos de Permissao

Ao criar uma API Key, voce pode definir exatamente quais operacoes ela pode realizar. Isso segue o principio de menor privilegio -- cada chave deve ter apenas as permissoes necessarias.

Tabela de Permissoes

Permissao	Descricao	Operacoes Permitidas
channels.read	Ler canais	Listar canais, verificar status de conexao
channels.write	Gerenciar canais	Criar, conectar, desconectar e excluir canais
messages.send	Enviar mensagens	Enviar texto, imagem, video, audio, documento, contato, template
messages.read	Ler mensagens	Listar mensagens de uma conversa, buscar mensagem por ID
conversations.read	Ler conversas	Listar conversas, detalhes de uma conversa
conversations.write	Gerenciar conversas	Atribuir, transferir, fechar conversas
contacts.read	Ler contatos	Listar contatos, buscar contato por ID
contacts.write	Gerenciar contatos	Criar, atualizar e excluir contatos
webhooks.read	Ler webhooks	Listar webhooks e consultar logs de entrega
webhooks.write	Gerenciar webhooks	Criar, atualizar e excluir webhooks
bulk-send.write	Envio em massa	Criar e cancelar campanhas de envio em massa
bulk-send.read	Ler envios em massa	Listar campanhas e consultar status
sandbox.write	Sandbox	Usar endpoints de teste do sandbox

Exemplo: Chave Somente Leitura

{
  "name": "Dashboard Analytics",
  "permissions": [
    "messages.read",
    "conversations.read",
    "contacts.read",
    "channels.read"
  ]
}

Exemplo: Chave para Envio

{
  "name": "Bot de Notificacoes",
  "permissions": [
    "messages.send",
    "contacts.read"
  ]
}

Exemplo: Chave para Sandbox

{
  "name": "Testes de Integracao",
  "permissions": [
    "sandbox.write",
    "messages.send"
  ],
  "environment": "test"
}

---

Rate Limits (Limites de Requisicao)

Para garantir a estabilidade da plataforma, o Ogmma API aplica limites de requisicao por minuto. Esses limites variam de acordo com o plano da sua instituicao.

Limites por Plano

Plano	Requisicoes/min	Mensagens/dia	Canais	Descricao
Free	20	100	1	Para testes e avaliacoes
Starter	60	1.000	3	Para pequenas empresas
Professional	200	10.000	10	Para empresas em crescimento
Enterprise	1.000	Ilimitado	Ilimitado	Para grandes operacoes

Headers de Rate Limit

Todas as respostas da API incluem headers informativos sobre seu consumo:

Header	Descricao
X-RateLimit-Limit	Limite total de requisicoes por minuto
X-RateLimit-Remaining	Requisicoes restantes na janela atual
X-RateLimit-Reset	Timestamp (Unix) de quando o limite sera resetado

Exemplo de Response Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705323660

Quando o Limite e Atingido

Se voce exceder o limite, a API retorna 429 Too Many Requests:

{
  "message": "Limite de requisicoes excedido. Tente novamente em 32 segundos.",
  "code": "RATE_LIMIT_EXCEEDED"
}

Campo	Tipo	Descricao
message	string	Mensagem de erro
code	string	Codigo do erro

Boas Praticas

• Implemente retry com backoff exponencial -- ao receber 429, espere o tempo indicado em retryAfter antes de tentar novamente
• Use webhooks ao inves de polling -- ao inves de consultar o status repetidamente, configure um webhook para ser notificado automaticamente
• Agrupe operacoes -- use o endpoint de envio em massa ao inves de enviar mensagens individualmente em loop

---

Erros de Autenticacao

Status	Codigo	Descricao
401	UNAUTHORIZED	Token ou API Key ausente ou invalido
401	AUTHENTICATION_REQUIRED	Header Authorization nao enviado
401	INVALID_API_KEY	API Key invalida, expirada ou revogada
401	INVALID_TOKEN	JWT invalido ou expirado
403	FORBIDDEN_PERMISSION	API Key nao possui a permissao necessaria
429	RATE_LIMIT_EXCEEDED	Limite de requisicoes excedido

Exemplo: 401 Unauthorized

{
  "message": "Token de autenticacao invalido ou expirado",
  "code": "UNAUTHORIZED"
}

Exemplo: 403 Permissao Insuficiente

{
  "message": "API Key nao possui permissao para esta operacao",
  "code": "FORBIDDEN_PERMISSION"
}

---

Recomendacoes de Seguranca

1. Nunca exponha API Keys no frontend -- use apenas no backend (server-side)
2. Use escopos restritos -- cada chave deve ter apenas as permissoes necessarias
3. Defina expiracao quando possivel -- chaves temporarias para integracoes especificas
4. Rotacione chaves periodicamente -- crie uma nova chave e revogue a antiga
5. Armazene com seguranca -- use variaveis de ambiente ou cofres de secrets (ex: AWS Secrets Manager, Vault)
6. Monitore uso -- verifique lastUsedAt na listagem de API Keys para identificar chaves nao utilizadas

---

Proximos Passos

Agora que voce entende a autenticacao, explore os endpoints da API:

• Canais -- Gerencie seus canais WhatsApp
• Mensagens -- Envie todos os tipos de mensagem
• Webhooks -- Receba eventos em tempo real
• Envio em Massa -- Dispare campanhas de mensagens