Conexão hospedada (white label)
Ofereça "Conectar Instagram" dentro do seu sistema. Cada usuário seu conecta a conta dele por um link assinado, numa página com a sua marca, sem criar conta no CrazyLeads. A conta vira uma fonte no seu projeto, e você lê perfil, posts e métricas pela API.
Como funciona
Seu servidor CrazyLeads (seu projeto) Instagram
──────────── ──────────────────────── ─────────
gera o link assinado ───────▶ /h/{projeto} (página com a sua marca)
(ref = id do usuário) [Conectar Instagram] ─────────────────▶ login do usuário
"Ligar @conta a {sua marca}?" ◀────── autorização
cria a fonte do Instagram (ref)
◀── volta ao seu return_url ─── ?status=connected&connection_id=…&sig=…
lê os dados pela API v1, filtrando pelo external_refVocê usa um projeto para todos os seus usuários. Cada conexão guarda o external_ref, que é o id do usuário no seu sistema (opaco para nós), e vira uma fonte comum do projeto. A página mostra a sua marca, com um rodapé discreto "Conexão operada por CrazyLeads". Na tela de permissão do Instagram aparece o app do CrazyLeads: é a Meta que mostra o app que pede o acesso.
O Instagram só libera esta conexão para contas profissionais (Criador de conteúdo ou Comercial). A página explica isso ao usuário antes do botão e mostra como trocar, que é grátis.
Credenciais
Use uma das duas, conforme o seu caso:
API key do projeto (mais simples)
Em Configurações → Desenvolvedores → Chaves do projeto, crie uma chave de escopo global com a permissão hosted_connections:write. Mande-a em Authorization: Bearer dskey_… (ou X-API-Key). Se a chave tiver lista de IPs, ela vale nestas rotas também. Chave revogada deixa de valer em até 1 minuto.
Token de app parceiro (OAuth)
Para quem já tem um app parceiro: peça o escopo hosted_connections:manage na autorização. A pessoa que autoriza precisa poder editar o projeto.
Passo a passo
Configure o modo no projeto
Em Configurações → Desenvolvedores → Conexão hospedada: ligue o modo, dê nome, logo e cor à sua marca e cadastre as URLs de retorno (o ret do link precisa ser igual a uma delas, letra por letra). Se for embutir a página num iframe, cadastre a origem do seu site. Cadastre também os IPs do seu servidor. Depois, clique em Gerar segredo e guarde o kid e o segredo no seu servidor: eles aparecem uma vez só.
Gere o link no clique do usuário
O link vale por até 10 minutos e uma vez só. Gere no momento em que o usuário clica em "Conectar Instagram" no seu sistema, só para quem está logado como aquele ref, e redirecione na hora. Você pode assinar no seu servidor (sem chamar a API):
import crypto from "node:crypto";
// Gere NO SERVIDOR, no clique do usuário. O segredo nunca vai ao navegador.
export function linkDeConexao({ projeto, kid, segredo, ref, ret, ip }) {
const exp = Math.floor(Date.now() / 1000) + 600; // até 10 minutos
const nonce = crypto.randomBytes(18).toString("base64url");
const canonico = ["v1", projeto, "instagram", ref, String(exp), ret ?? "", nonce, kid, ip ?? ""].join("\n");
const sig = crypto.createHmac("sha256", segredo).update(canonico).digest("base64url");
const url = new URL(`https://crazyleads.com.br/h/${projeto}`);
url.searchParams.set("type", "instagram");
url.searchParams.set("ref", ref);
url.searchParams.set("exp", String(exp));
if (ret) url.searchParams.set("ret", ret);
url.searchParams.set("nonce", nonce);
url.searchParams.set("kid", kid);
if (ip) url.searchParams.set("ip", ip);
url.searchParams.set("sig", sig);
return url.toString();
}import base64, hashlib, hmac, secrets, time
from urllib.parse import urlencode
def link_de_conexao(projeto, kid, segredo, ref, ret=None, ip=None):
exp = int(time.time()) + 600 # até 10 minutos
nonce = secrets.token_urlsafe(18)
canonico = "\n".join(["v1", projeto, "instagram", ref, str(exp), ret or "", nonce, kid, ip or ""])
sig = base64.urlsafe_b64encode(
hmac.new(segredo.encode(), canonico.encode(), hashlib.sha256).digest()
).rstrip(b"=").decode()
params = {"type": "instagram", "ref": ref, "exp": exp, "nonce": nonce, "kid": kid, "sig": sig}
if ret: params["ret"] = ret
if ip: params["ip"] = ip
return f"https://crazyleads.com.br/h/{projeto}?" + urlencode(params)A string assinada é, nesta ordem e separada por quebra de linha: v1, uuid do projeto, instagram, ref, exp, ret, nonce, kid e ip. Os campos opcionais vazios entram como texto vazio. A assinatura é HMAC-SHA256 em base64url, sem =.
Ou peça o link pronto à API, sem guardar o segredo:
curl -X POST https://crazyleads.com.br/api/v1/projects/0b8f7c3e-1d2a-4c5b-9e6f-7a8b9c0d1e2f/hosted-links \
-H "Authorization: Bearer dskey_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{"external_ref": "criador_42", "return_url": "https://app.seusistema.com/instagram/volta"}'
# 201
{ "url": "https://crazyleads.com.br/h/0b8f7c3e-1d2a-4c5b-9e6f-7a8b9c0d1e2f?type=instagram&ref=criador_42&…&sig=…",
"expires_at": "2026-11-16T18:10:00.000Z" }Campos: external_ref (obrigatório, até 128 caracteres de A-Z a-z 0-9 . _ : -), return_url e ip (opcionais).
O usuário conecta
Ele abre o link, entra com o Instagram numa janela e confirma "Ligar @conta a {sua marca}?". Só aí a fonte é criada e começa a coletar (a primeira coleta sai na hora, depois todo dia). Se a mesma conta já estava ligada no projeto, o acesso é renovado na mesma fonte, e um ref diferente transfere a conta para o novo ref.
Receba o retorno e confira a assinatura
O usuário volta ao seu return_url com status (connected, cancelled ou error), connection_id, ref, ts, kid e sig. A assinatura usa o mesmo segredo do link, sobre v1, status, connection_id, ref e ts. Confira antes de confiar, ou confirme pela API:
import crypto from "node:crypto";
// Na sua URL de retorno: confira a assinatura ANTES de confiar no status.
export function conferirRetorno(url, segredo) {
const q = new URL(url).searchParams;
const ts = Number(q.get("ts"));
if (!ts || Math.abs(Date.now() / 1000 - ts) > 600) return null; // retorno velho
const canonico = ["v1", q.get("status"), q.get("connection_id") ?? "", q.get("ref"), String(ts)].join("\n");
const esperado = crypto.createHmac("sha256", segredo).update(canonico).digest("base64url");
const sig = q.get("sig") ?? "";
if (sig.length !== esperado.length || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(esperado))) return null;
return { status: q.get("status"), connectionId: q.get("connection_id"), ref: q.get("ref") };
}Página num iframe: em vez de navegar, ela manda postMessage({ type: "crazyleads:conexao-hospedada", url, status, connection_id, ref, ts, kid, sig }) para a origem do retorno e para as origens cadastradas. Confira event.origin e a assinatura do mesmo jeito.
Liste e revogue
curl "https://crazyleads.com.br/api/v1/projects/0b8f7c3e-1d2a-4c5b-9e6f-7a8b9c0d1e2f/connections?external_ref=criador_42" \
-H "Authorization: Bearer dskey_SUA_CHAVE"
{ "data": [ { "id": "ckx…", "type": "instagram", "external_ref": "criador_42",
"source_id": "6f1c…", "ig_user_id": "17841400000000001",
"username": "ana.cria", "status": "ativa",
"connected_at": "2026-11-16T18:02:11.000Z", "revoked_at": null } ],
"next_cursor": null }Filtros: external_ref, status (ativa ou revogada), cursor e limit (1–200). Com o source_id, leia perfil, posts e métricas pelas rotas de Instagram da API v1. Hoje essas rotas de leitura pedem o token de app parceiro, com o escopo instagram_content:read; a API key cobre gerar links, listar e revogar.
curl -X DELETE https://crazyleads.com.br/api/v1/projects/0b8f7c3e-1d2a-4c5b-9e6f-7a8b9c0d1e2f/connections/ckx… \
-H "Authorization: Bearer dskey_SUA_CHAVE"
{ "id": "ckx…", "status": "revogada" }Revogar apaga a fonte e o acesso do usuário, e pode ser repetido sem erro. Se o usuário tirar o app nas configurações do Instagram, a conexão é revogada sozinha. Quando receber uma revogação, apague também a cópia dos dados dele no seu sistema.
Restrição de IP
Há duas camadas, e você pode usar as duas:
- IPs do seu servidor: a lista do modo (IP ou faixa CIDR, IPv4 e IPv6) vale para as rotas da API acima. A lista da própria API key também vale. Lista vazia aceita qualquer IP.
- IP do usuário no link (opcional): mande o IP do usuário no parâmetro
ip, que entra na assinatura. A página recusa quem abrir de outra rede. Cuidado com celular, que troca de IP entre 4G e Wi-Fi.
Segurança
- O segredo e a API key ficam só no seu servidor. Nunca os mande ao navegador.
- Gere o link só para o usuário logado como aquele
ref. Quem tem o link liga uma conta àqueleref; por isso ele vale minutos e uma vez só. - Confira a assinatura do retorno e o
event.originno iframe. - Para trocar o segredo, gere um novo: o anterior continua valendo por 24 h, e o
kiddiz qual assinou. - Link recusado (assinatura, prazo, já usado, IP) mostra sempre a mesma tela, sem dizer o motivo.
Erros e limites
| Resposta | Quando | O que fazer |
|---|---|---|
401 invalid_token | API key inválida, vencida ou revogada; ou token de app vencido. | Gere outra chave ou renove o token. |
403 insufficient_scope | A chave não tem hosted_connections:write (ou o app não tem hosted_connections:manage). | Edite a permissão da chave. |
403 ip_not_allowed | O IP do seu servidor está fora da lista do modo ou da lista da própria chave. | Inclua o IP/CIDR nas duas listas. |
404 not_found | Projeto que não é o da credencial, conexão inexistente ou modo nunca configurado. | Confira o uuid do projeto. |
409 project_frozen | O projeto está congelado (assinatura): gerar link fica parado. | Reative o projeto. Listar e revogar continuam. |
409 precondition_failed | Projeto ainda não liberado, modo desligado ou sem segredo de assinatura. | Ligue o modo e gere o segredo; peça a liberação. |
400 invalid_request | external_ref, return_url ou ip fora do formato; return_url fora da lista do projeto. | A mensagem diz o campo. |
429 rate_limited | Mais de 120 links por minuto pela mesma credencial, ou chamadas demais do mesmo IP. | Respeite o Retry-After. |
503 unavailable | Não deu para apagar a fonte agora ao revogar. | Tente de novo; revogar é idempotente. |
Os erros seguem as convenções da API. O projeto tem um limite de contas conectadas (200 por padrão; ajuste em Configurações). Passou dele, o usuário vê o aviso e você recebe status=error no retorno.