Iniciar sessãoIniciar teste gratuito
easyCoexistence APIs oficiais

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.

ec_live_

O prefixo com que começa cada chave da Partner API, enviada em cada pedido como Authorization: Bearer.

1 key

Chaves que uma conta detém em simultâneo; cada ligação feita com ela pertence a essa conta.

401

Estado para uma chave em falta ou inválida, com o código unauthorized e uma mensagem que indica o cabeçalho esperado.

Once

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.

List the account's numbers
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_key com replace_existing definido 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_key com 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.

401 Unauthorized
{
  "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_reached ou rate_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.
Fazer isto com a EasyCoexistence

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