Autenticação

A API v1 usa chaves de API com o prefixo ea_live_. Cada chave é vinculada a um único time: o time é resolvido automaticamente pela API e o consumidor não deve enviar team_id.

Header obrigatório

Nos endpoints autenticados por chave, envie a chave no header Authorization:

Authorization: Bearer ea_live_sua_chave_aqui

Criação e armazenamento

Crie chaves em Configurações → Integrações → API. O valor completo é exibido apenas uma vez, no momento da criação. A Colmeia armazena somente o hash da chave; para invalidá-la, revogue-a pelo painel.

Exemplos

Use uma variável de ambiente chamada COLMEIA_API_KEY em todos os ambientes.

cURL

curl -sS "https://app.usecolmeia.com/api/v1/clients?limit=10" \
  -H "Authorization: Bearer $COLMEIA_API_KEY"

JavaScript

const response = await fetch('https://app.usecolmeia.com/api/v1/clients?limit=10', {
  headers: {
    Authorization: `Bearer ${process.env.COLMEIA_API_KEY}`,
  },
});

const payload = await response.json();

Python

import os
import requests

response = requests.get(
    'https://app.usecolmeia.com/api/v1/clients?limit=10',
    headers={'Authorization': f"Bearer {os.environ['COLMEIA_API_KEY']}"},
)
payload = response.json()

Erros de autenticação

As situações abaixo retornam 401 Unauthorized:

• Header Authorization ausente ou malformado
• Chave sem o prefixo ea_live_
• Chave inexistente
• Chave inativa ou revogada

Uma resposta segue este formato:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Rotação segura

1. Crie uma nova chave no painel.
2. Atualize todos os consumidores para a nova variável de ambiente.
3. Valide as integrações com uma requisição autenticada.
4. Revogue a chave anterior no painel.

Assim, a chave antiga continua disponível apenas durante a transição e deixa de autenticar imediatamente após a revogação.

Proteja suas chaves

Nunca coloque uma chave de API em:

• Código executado no browser
• Query string ou URL
• Repositório de código
• Logs, mensagens de erro ou ferramentas de observabilidade

Para começar a usar os recursos autenticados, siga o Início rápido.