API Keys

Conceituacao

As API Keys sao o principal metodo de autenticacao da Ogmma API. Cada chave identifica a sua instituicao e define quais operacoes estao autorizadas, permitindo controle granular de acesso aos recursos da plataforma.

Formato da chave

As API keys seguem o formato padrao:

oapi_sk_{environment}_{random}

Componente	Descricao
oapi_sk_	Prefixo fixo que identifica uma chave Ogmma
{environment}	Ambiente: live (producao) ou test (sandbox)
{random}	Sequencia aleatoria unica

Comprimento total: 48 caracteres.

Exemplos:

• Producao: oapi_sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
• Sandbox: oapi_sk_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Ambientes

Ambiente	Prefixo	Descricao
live	oapi_sk_live_	Chave de producao. Acessa canais reais e envia mensagens de verdade.
test	oapi_sk_test_	Chave de teste. Acessa o ambiente sandbox com mensagens simuladas.

Propriedades da chave

Cada API key possui as seguintes propriedades:

Propriedade	Descricao
Nome	Nome descritivo para identificar o uso da chave (ex: "Integracao CRM", "Webhook Producao")
Permissoes	Lista de escopos granulares que definem quais operacoes a chave pode executar
Rate Limit	Limite de requisicoes por minuto para esta chave especifica
Data de Expiracao	Data opcional em que a chave sera automaticamente desativada

Seguranca

As API keys sao armazenadas como hashes SHA-256. Isso significa que:

• O valor completo da chave e exibido apenas uma vez, no momento da criacao.
• Apos a criacao, somente o prefixo (primeiros 8 caracteres) e visivel.
• Nao e possivel recuperar uma chave perdida. Nesse caso, revogue a chave antiga e crie uma nova.

Autenticacao

Para autenticar uma requisicao, inclua a API key no header Authorization:

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

Escopos de permissao

As permissoes sao definidas de forma granular por recurso e operacao:

Escopo	Descricao
channels.read	Listar e visualizar canais
channels.write	Criar e gerenciar canais
messages.send	Enviar mensagens
messages.read	Ler mensagens
conversations.read	Listar e visualizar conversas
conversations.write	Gerenciar conversas (fechar, transferir)
contacts.read	Listar e visualizar contatos
contacts.write	Criar e editar contatos
webhooks.read	Listar webhooks configurados
webhooks.write	Criar e gerenciar webhooks
bulk-send.write	Criar envios em massa
bulk-send.read	Consultar status de envios em massa
sandbox.write	Executar operacoes no sandbox

Boas praticas

• Use chaves diferentes para cada integracao - Facilita a auditoria e permite revogar acesso individualmente.
• Rotacione as chaves periodicamente - Crie uma nova chave, atualize sua integracao e revogue a antiga.
• Use chaves de teste para desenvolvimento - Nunca use chaves live em ambientes de desenvolvimento.
• Nunca exponha chaves em codigo client-side - API keys devem ser usadas apenas em servidores backend.
• Defina permissoes minimas - Conceda apenas os escopos necessarios para cada integracao.
• Configure data de expiracao - Para chaves temporarias, defina uma data de expiracao automatica.

Atencao

Nunca compartilhe suas API keys em repositorios de codigo, logs ou comunicacoes nao seguras. Se uma chave for comprometida, revogue-a imediatamente.