EntrarComeçar teste grátis
easyCoexistence APIs oficiais

Autenticação da Partner API: chaves Bearer ec_live_, rotação e erros 401

Toda requisição da Partner API leva a chave secreta da conta no cabeçalho Authorization: Bearer ec_live_…, enviada pelo seu servidor. Cada conta do easyCoexistence tem uma chave, criada no painel em Profile, Developers, ou pedindo a um assistente de IA que execute create_api_key, e exibida apenas uma vez. Rotacionar a chave emite uma nova e encerra a antiga na hora; uma chave ausente ou errada recebe 401 unauthorized.

ec_live_

O prefixo com que toda chave da Partner API começa, enviado em cada requisição como Authorization: Bearer.

1 key

Chaves que uma conta mantém ao mesmo tempo; cada conexão feita com ela pertence a essa conta.

401

Status para chave ausente ou inválida, com o código de erro unauthorized e uma mensagem que nomeia o cabeçalho esperado.

Once

Momentos em que a chave completa é exibida: na criação ou na rotação; depois, só os primeiros caracteres aparecem.

Como uma requisição se autentica?

Com a chave como token Bearer no cabeçalho Authorization de toda requisição para https://easycoexistence.com/api/v1. Nada mais é assinado ou limitado por escopo: a chave identifica a conta, e tudo que uma requisição cria ou lê pertence a essa conta. Os corpos são JSON, e todo erro volta como um objeto com code e message.

List the account's numbers
curl https://easycoexistence.com/api/v1/connections \
  -H "Authorization: Bearer $EC_API_KEY"

Onde você cria a chave?

No painel ou com um assistente de IA, com o mesmo resultado. No painel, abra Profile, depois Developers, e pressione Create API key. No Claude, ChatGPT ou outro assistente conectado ao servidor MCP do easyCoexistence, peça para configurar a Partner API: get_partner_setup mostra o que falta, e create_api_key devolve a chave. De qualquer forma, a chave completa aparece uma vez, então guarde-a nos segredos do seu backend imediatamente.

Por que a chave é exibida só uma vez?

Porque só um hash dela é armazenado. O easyCoexistence guarda o hash para verificar cada requisição, além dos primeiros caracteres da chave, ec_live_ e mais seis, para que o painel mostre qual chave está ativa e quando foi criada. Uma chave perdida não pode ser exibida de novo; rotacioná-la a substitui.

Como você rotaciona ou revoga a chave?

Em um passo, e a chave antiga para de funcionar naquele momento, sem período de carência, já que um vazamento é o motivo mais comum para rotacionar. A nova chave é exibida uma vez, como a primeira:

  • Painel: Profile, Developers, Rotate key.
  • MCP: create_api_key com replace_existing definido como true. Sem isso, a ferramenta recusa enquanto existir uma chave, para que uma integração em execução não seja quebrada por acidente.
  • Para interromper todo acesso, revogue: Revoke no painel, ou revoke_api_key com confirm definido como true. As requisições então falham até que uma nova chave seja criada.

O que retorna uma chave ausente ou errada?

Um 401 com o código unauthorized, para uma requisição sem cabeçalho Authorization, uma chave que não começa com ec_live_, ou uma chave que foi rotacionada ou revogada. A mensagem nomeia o cabeçalho esperado. Quando requisições com falha continuam vindo de um mesmo endereço, a API responde 429 rate_limited, com os segundos a esperar antes de repetir.

401 Unauthorized
{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key. Send `Authorization: Bearer ec_live_...`."
  }
}

Que outros motivos podem recusar uma chave válida?

Uma chave válida autentica a conta, e o estado da conta continua valendo. Estes retornam com o mesmo formato de erro:

  • 402 billing_required: a conta ainda não tem cartão, então não pode iniciar sessões de conexão.
  • 404 not_found: o id não pertence a nenhuma conexão, canal ou sessão desta conta, incluindo as de outras contas.
  • 409 removed: a conexão foi removida, então o seu webhook não pode mudar.
  • 402 suspended: a conexão está suspensa após uma assinatura vencida; reconecte-a primeiro.
  • 429 cap_reached ou rate_limited: sessões de conexão abertas demais, ou criadas demais nesta hora.

Erros comuns

  • Colocar a chave no código do front-end. Qualquer pessoa que abrir a página pode lê-la, criar conexões cobradas de você e buscar os tokens dos seus clientes com ?credentials=1.
  • Rotacionar antes que o seu backend consiga usar a nova chave. A antiga para na hora, então toda requisição falha com 401 até a nova ser implantada.
  • Criar a chave em uma conversa compartilhada. create_api_key a devolve no chat, onde ela fica no histórico; então rotacione-a se essa conversa for compartilhada.
  • Guardar a chave entre aspas. Tudo depois de Bearer é lido como a chave, então um valor entre aspas nunca confere e toda requisição recebe 401.
Fazendo isso com o EasyCoexistence

O easyCoexistence dá a cada conta uma chave da Partner API, para que o seu backend conecte os números de WhatsApp dos seus clientes e as contas deles de Instagram, Facebook, TikTok, YouTube e LinkedIn, e os canais que forem chegando, depois leia as credenciais de cada conexão e roteie os eventos dela. De US$ 9 a US$ 0.75 por conexão por mês, caindo conforme você adiciona conexões, com os primeiros 3 dias grátis.

O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.

Perguntas frequentes

Uma conta pode ter mais de uma chave da API?

Não. Uma conta tem uma chave por vez, e criar uma nova substitui a anterior. Chaves separadas significam contas separadas no easyCoexistence, cada uma com suas próprias conexões e sua própria cobrança.

As chaves da Partner API expiram?

Não. Uma chave funciona até ser rotacionada ou revogada, ou até o easyCoexistence encerrá-la por abuso das regras da Meta.

Meus clientes precisam da minha chave para conectar?

Não. Eles só abrem o link de conexão hospedado, que traz o próprio id de sessão. A chave fica no seu servidor e é usada apenas pelo seu backend.

A chave da API é o mesmo que o segredo de assinatura dos eventos?

Não. A chave autentica as suas requisições à API. O segredo de assinatura, exibido uma vez quando você define uma URL de eventos de status, permite que o seu endpoint verifique os eventos que o easyCoexistence envia.

Continue lendo

Conecte seu primeiro canal em dois minutos.

Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.

  • 3 dias grátis
  • Cancele quando quiser
  • Só APIs oficiais
  • Monitorado 24/7

Verificado em