Onboarding hospedado

Os clientes do seu produto conectam o próprio Instagram sem criar conta na Keymatic. Seu backend recebe uma chave por conta; ninguém vê token da Meta.

Como funciona

Projeto: criado no console antes de existir qualquer Instagram, com nome, permissões permitidas e URLs de retorno exatas.
Chave de projeto km_proj_: só gerencia conexões. Não lê nem escreve dados do Instagram e não funciona no MCP.
Concessão: o cliente final autorizou a conta X ao projeto com as permissões Y. As chaves filhas km_api_ valem enquanto projeto e concessão estão ativos.
A mesma conta em dois projetos ocupa uma licença. Conta nova consome vaga do plano; sem vaga, o retorno traz erro=limite_de_contas.

Os quatro passos

Crie o projeto em Projetos com a URL HTTPS exata do callback (1 a 5 URLs, sem fragmento). Guarde km_proj_ no gerenciador de segredos do backend; o segredo aparece uma vez e a chave vale 365 dias.
Abra uma sessão com POST /conexoes/sessoes, um state aleatório de uso único associado ao seu cliente e as permissões desejadas. Redirecione o navegador para a url recebida, sem reconstruí-la. O ticket dura 10 min e não abre em outro navegador.
O cliente autoriza na página hospedada da Keymatic, que mostra quem pede acesso, e depois no diálogo oficial da Meta. Ao final, o navegador volta para url_retorno?code=…&state=… ou ?erro=…&state=….
Troque o code no servidor com POST /conexoes/codigos, depois de validar o state. A resposta traz conta_id, username, permissões, recursos e a chave km_api_ da conta. Guarde cifrada e nunca devolva ao navegador.

O code vale 5 min e é de uso único. Não aplique retry automático na troca: repetir devolve 409 code_invalido e revoga a chave emitida. Se a resposta se perdeu, peça uma nova conexão.

# No backend do CRM, com a chave de projeto
curl -X POST "https://ig.keymatic.com.br/api/instagram/conexoes/sessoes" \
  -H "Authorization: Bearer $KEYMATIC_PROJECT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url_retorno":"https://app.seu-crm.com/integracoes/keymatic/retorno","state":"<nonce-do-crm>","permissoes":["ler","mensagens"]}'

# 201
{"sessao_id":"<uuid>","url":"https://ig.keymatic.com.br/api/instagram/conexoes/hospedada?ticket=<ticket>","expira_em":"..."}

Erros no retorno

O parâmetro erro chega com o mesmo state que você enviou:

Código	O que fazer
`acesso_negado`	O cliente cancelou. Ofereça tentar de novo.
`instagram_em_outra_conta`	A conta já pertence a outro tenant Keymatic e não é transferida em silêncio.
`limite_de_contas`	O plano não tem vaga para outra conta. Amplie as licenças no console.
`assinatura_api`	Plano sem API Keymatic ou pagamento pendente.
`projeto_revogado`	O projeto foi revogado no console.
`sessao_expirada`	Ticket ou consentimento expirou. Abra uma nova sessão.
`falha_login`	O login na Meta não terminou. Abra uma nova sessão.

Depois da conexão

A chave filha usa a API Keymatic normalmente. Vale 90 dias, 60 req/min, com as permissões consentidas.
Renove por POST /conexoes/contas/{conta_id}/credenciais; revogue a concessão por DELETE /conexoes/contas/{conta_id}.
Revogar o projeto no console derruba chaves de projeto, concessões, chaves filhas e sessões abertas, e pausa as regras automáticas criadas por ele.
Pedir publicar faz a página solicitar também publicação e métricas à Meta. Sem App Review em produção, use só com contas testadoras.