Autenticação e chaves

Toda chamada à API e ao servidor MCP é autenticada com uma chave de API da sua organização. A chave começa com tt_live_.

Como enviar a chave

Use o cabeçalho Authorization com o esquema Bearer:

Authorization: Bearer tt_live_SUA_CHAVE

Se a ferramenta que você usa só permite um cabeçalho “API key” com nome livre, também aceitamos:

X-Api-Key: tt_live_SUA_CHAVE

Criar uma chave

Só administradores da organização criam e revogam chaves. As chaves estão disponíveis em todos os planos.

1. No painel, abra Configurações → Desenvolvedor.
2. No cartão Chaves de API, clique em Criar chave.
3. Preencha:
   • Nome: quem ou o que vai usar a chave (ex.: “Integração do ERP”, “Claude do time de vendas”). Ajuda a saber o que revogar depois.
   • Acesso: Acesso total ou Somente leitura (veja abaixo).
   • Validade: sem validade, 30 dias, 90 dias ou 1 ano. Depois da validade a chave para de funcionar sozinha.
4. Copie a chave e guarde num cofre de senhas ou nos “secrets” do seu servidor. A chave completa aparece uma única vez — a TopTalking guarda só uma impressão digital (hash) dela. Se perder, revogue e crie outra.

Você pode ter até 25 chaves ativas por organização. Use uma chave por sistema, automação ou pessoa: assim dá para revogar uma sem derrubar as outras.

Níveis de acesso

Acesso	Valor em GET /me	O que pode fazer
Acesso total	full	Tudo: ler, enviar mensagens, criar e alterar contatos, mover cards, agendar, gerenciar webhooks.
Somente leitura	read	Só requisições GET. Qualquer outro método (POST, PATCH, DELETE) devolve 403 com o código read_only_key.

No servidor MCP, uma chave somente leitura só expõe as ferramentas de consulta. É a escolha certa para dashboards, relatórios e para explorar a API com uma IA sem risco de ela mandar mensagens.

Validade e revogação

• Validade: quando a data passa, a chave deixa de funcionar e a API responde 401 expired_api_key.
• Revogar: no cartão Chaves de API, clique em Revogar chave. O efeito é imediato e não tem volta: a API passa a responder 401 revoked_api_key.
• O painel mostra quando cada chave foi usada pela última vez — útil para achar chaves esquecidas.

Revogue a chave na hora se ela vazar (por exemplo, se foi parar num repositório público ou num print).

A chave nunca vai para o navegador

Importante

A chave dá acesso ao WhatsApp da empresa: com ela, qualquer pessoa pode ler conversas e mandar mensagens em seu nome. Nunca coloque a chave em código que roda no navegador ou no celular do usuário (React, Vue, Angular, HTML, JavaScript do site, app mobile, extensão de navegador).

Por isso a API não aceita chamadas do navegador (não envia cabeçalhos CORS, de propósito). Se você vir um erro de CORS no console, não é bug: é a API protegendo a sua conta. A solução é sempre a mesma — chamar a API de um backend:

Onde está o seu app	Onde colocar a chamada à API
Lovable / Supabase	Uma Supabase Edge Function, com a chave guardada como secret TOPTALKING_API_KEY. Veja o guia do Lovable.
Next.js / v0 / Vercel	Um Route Handler (app/api/.../route.ts) ou Server Action, com a chave em variável de ambiente. Veja Bolt, v0 e Replit.
Node, Python, PHP…	O seu servidor, com a chave em variável de ambiente.
Sem código	n8n, Make ou Zapier, no nó/módulo HTTP. Veja n8n, Make e Zapier.

O fluxo seguro fica assim:

Navegador do usuário  →  seu backend (guarda a chave)  →  API da TopTalking
     (sem chave)            Edge Function / rota / n8n

Exemplo: Supabase Edge Function como ponte

O front-end chama a sua função (com o login do usuário, se houver); a função chama a TopTalking com a chave guardada como secret:

Edge Function (Deno)

supabase/functions/toptalking-contatos/index.ts

const TOPTALKING_API = 'https://platform.toptalking.com.br/v1';

const cors = {
  'Access-Control-Allow-Origin': '*', // troque pelo domínio do seu app em produção
  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
};

Deno.serve(async (req) => {
  if (req.method === 'OPTIONS') return new Response('ok', { headers: cors });

  // A chave fica só aqui, no servidor (Secrets da Supabase / Lovable Cloud).
  const apiKey = Deno.env.get('TOPTALKING_API_KEY');
  if (!apiKey) return new Response('TOPTALKING_API_KEY não configurada', { status: 500, headers: cors });

  const res = await fetch(`${TOPTALKING_API}/contacts?limit=20`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  });

  return new Response(await res.text(), {
    status: res.status,
    headers: { ...cors, 'Content-Type': 'application/json' },
  });
});

Front-end (React)

src/lib/contatos.ts

import { supabase } from '@/integrations/supabase/client';

// O navegador chama a SUA função, nunca a TopTalking direto.
export async function listarContatos() {
  const { data, error } = await supabase.functions.invoke('toptalking-contatos');
  if (error) throw error;
  return data; // { object: "list", data: [...], has_more, next_cursor }
}

Não crie um “proxy aberto”

A função acima só lista contatos. Evite funções que repassam qualquer caminho ou corpo para a TopTalking: qualquer visitante do seu site conseguiria usar a sua chave. Faça uma função por ação (ex.: “enviar boas-vindas”), valide os dados e, se o app tiver login, exija o usuário logado.

Boas práticas com chaves

• Guarde a chave em variável de ambiente ou cofre de segredos, nunca no código nem no Git.
• Use uma chave por integração, com nome claro, e Somente leitura sempre que não precisar escrever.
• Prefira chaves com validade para testes e integrações temporárias.
• Para agentes de IA (MCP, GPTs), comece com uma chave Somente leitura.
• Revogue chaves que não aparecem como usadas há muito tempo.

Erros de autenticação

HTTP	code	Quando acontece	O que fazer
401	missing_api_key	Nenhuma chave foi enviada.	Envie Authorization: Bearer tt_live_....
401	invalid_api_key	A chave não existe ou foi digitada errada.	Copie a chave de novo (sem espaços extras) ou crie outra.
401	revoked_api_key	A chave foi revogada no painel.	Crie uma chave nova.
401	expired_api_key	A validade da chave acabou.	Crie uma chave nova.
403	read_only_key	Chave Somente leitura tentou POST, PATCH ou DELETE.	Use uma chave com Acesso total.

Veja todos os códigos em Erros.