Autenticação da Partner API: chaves Bearer ec_live_, rotação e erros 401
Cada pedido à Partner API leva a chave secreta da conta no cabeçalho Authorization: Bearer ec_live_…, enviada a partir do seu servidor. Cada conta da easyCoexistence tem uma chave, criada no painel em Profile, Developers, ou pedindo a um assistente de IA que execute create_api_key, e mostrada apenas uma vez. Rodar a chave emite uma nova e termina a antiga de imediato; uma chave em falta ou errada devolve 401 unauthorized.
O prefixo com que começa cada chave da Partner API, enviada em cada pedido como Authorization: Bearer.
Chaves que uma conta detém em simultâneo; cada ligação feita com ela pertence a essa conta.
Estado para uma chave em falta ou inválida, com o código unauthorized e uma mensagem que indica o cabeçalho esperado.
Vezes em que a chave completa é mostrada, quando é criada ou rodada; depois, só os primeiros caracteres ficam visíveis.
Como é que um pedido se autentica?
Com a chave como token Bearer no cabeçalho Authorization de cada pedido a https://easycoexistence.com/api/v1. Nada mais é assinado nem tem âmbito definido: a chave identifica a conta, e tudo o que um pedido cria ou lê pertence a essa conta. Os corpos são JSON, e cada erro chega como um objeto com um código e uma mensagem.
curl https://easycoexistence.com/api/v1/connections \
-H "Authorization: Bearer $EC_API_KEY"Onde é que se cria a chave?
No painel ou a partir de um assistente de IA, com o mesmo resultado. No painel, abra Profile, depois Developers, e carregue em Create API key. No Claude, no ChatGPT ou noutro assistente ligado ao servidor MCP da easyCoexistence, peça-lhe para configurar a Partner API: get_partner_setup mostra o que falta e create_api_key devolve a chave. Em qualquer dos casos, a chave completa aparece uma vez, por isso guarde-a de imediato nos segredos do seu backend.
Porque é que a chave só é mostrada uma vez?
Porque só é guardado um hash dela. A easyCoexistence guarda o hash para verificar cada pedido, mais os primeiros caracteres da chave, ec_live_ e mais seis, para que o painel possa mostrar qual chave está ativa e quando foi criada. Uma chave perdida não pode voltar a ser mostrada; rodar substitui-a.
Como se roda ou revoga a chave?
Num só passo, e a chave antiga deixa de funcionar nesse momento, sem período de graça, já que uma fuga é o motivo habitual para rodar. A nova chave é mostrada uma vez, como a primeira:
- Painel: Profile, Developers, Rotate key.
- MCP:
create_api_keycomreplace_existingdefinido como true. Sem isso, a ferramenta recusa-se enquanto existir uma chave, para que uma integração em funcionamento não seja interrompida por acidente. - Para parar todo o acesso em vez disso, revogue: Revoke no painel, ou
revoke_api_keycom confirm definido como true. Os pedidos falham então até ser criada uma nova chave.
O que devolve uma chave em falta ou errada?
Um 401 com o código unauthorized, para um pedido sem cabeçalho Authorization, uma chave que não começa por ec_live_, ou uma chave que foi rodada ou revogada. A mensagem indica o cabeçalho esperado. Quando os pedidos falhados continuam a vir de um mesmo endereço, a API responde 429 rate_limited, com os segundos a esperar antes de voltar a tentar.
{
"error": {
"code": "unauthorized",
"message": "Missing or invalid API key. Send `Authorization: Bearer ec_live_...`."
}
}Que outras recusas pode uma chave válida receber?
Uma chave válida autentica a conta, e o estado da conta continua a aplicar-se. Estas respostas chegam com a mesma forma de erro:
- 402
billing_required: a conta ainda não tem cartão, por isso não pode iniciar sessões de ligação. - 404
not_found: o id não pertence a nenhuma ligação, canal ou sessão desta conta, incluindo as de outras contas. - 409 removed: a ligação foi removida, pelo que o seu webhook já não pode ser alterado.
- 402 suspended: a ligação está suspensa após uma subscrição caducada; reative-a primeiro.
- 429
cap_reachedourate_limited: demasiadas sessões de ligação abertas, ou demasiadas criadas nesta hora.
Erros comuns
- Pôr a chave no código do front-end. Qualquer pessoa que abra a página pode lê-la, criar ligações cobradas a si e obter os tokens dos seus clientes com ?credentials=1.
- Rodar antes de o seu backend conseguir usar a nova chave. A chave antiga para de imediato, por isso todos os pedidos falham com 401 até a nova ser publicada.
- Criar a chave numa conversa partilhada. create_api_key devolve-a no chat, onde fica no histórico, por isso rode-a se essa conversa for partilhada.
- Guardar a chave com aspas à volta. Tudo depois de Bearer é lido como chave, por isso um valor entre aspas nunca coincide e todos os pedidos recebem 401.
A easyCoexistence dá a cada conta uma chave da Partner API, para que o seu backend possa ligar os números de WhatsApp dos seus clientes e as contas deles de Instagram, Facebook, TikTok, YouTube e LinkedIn, e mais canais, depois ler as credenciais de cada ligação e encaminhar os seus eventos. De US$ 9 a US$ 0.75 por ligação por mês, descendo à medida que adiciona ligações, com os primeiros 3 dias grátis.
Perguntas frequentes
Uma conta pode ter mais de uma chave de API?
Não. Uma conta tem uma chave de cada vez, e criar uma nova substitui a anterior. Chaves separadas significam contas separadas na easyCoexistence, cada uma com as suas ligações e a sua própria fatura.
As chaves da Partner API expiram?
Não. Uma chave funciona até ser rodada ou revogada, ou até a easyCoexistence a terminar por abuso das regras da Meta.
Os meus clientes precisam da minha chave para ligar?
Não. Eles apenas abrem o link de ligação alojado, que traz o seu próprio id de sessão. A chave fica no seu servidor e é usada apenas pelo seu backend.
A chave de API é a mesma coisa que o segredo de assinatura dos eventos?
Não. A chave autentica os seus pedidos à API. O segredo de assinatura, mostrado uma vez quando define um URL de eventos de estado, permite ao seu endpoint verificar os eventos que a easyCoexistence envia.
Continue a ler
Ligue o seu primeiro canal em dois minutos.
Sem revisões de plataformas para esperar. Ligue o WhatsApp, o Instagram, o TikTok ou outro canal, peça depois à sua IA que publique, responda ou faça um relatório, e veja-a trabalhar.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorizado 24/7
Verificado em