Autenticação

Três formas de autorizar, conforme quem chama: agente, linha de comando ou servidor. Cada credencial limita contas, permissões e validade.

Clientes MCP: login no navegador

O cliente faz OAuth 2.1 com Authorization Code, PKCE S256 e registro dinâmico. Você entra com a conta Keymatic, escolhe os Instagrams e confere as permissões no consentimento. Contas conectadas depois exigem nova autorização. Nenhuma chave é colada no cliente.

Access token dura 1 h; o refresh é rotativo e renova a validade por 30 dias.
O código de autorização é de uso único e vale 5 min.
Os scopes OAuth correspondem às permissões da tabela abaixo.

Comandos por cliente em Clientes MCP.

Claude Code

claude mcp add-json keymatic '{"type":"http","url":"https://ig.keymatic.com.br/api/mcp","oauth":{"scopes":"instagram:read"}}' --scope local
claude mcp login keymatic

CLI: keymatic login

Prévia DEV 0.1.0-dev.20261110.2 disponível para instalação pelo arquivo baixado. O pacote ainda não está no registro npm; não precisa de acesso ao repositório.

Baixar CLI (.tgz) e SHA256SUMS. O portão DEV também protege os downloads. Confira a soma antes de instalar.

Instalação DEV

# Primeiro baixe o pacote e SHA256SUMS nesta página.
shasum -a 256 -c SHA256SUMS
npm install --global ./keymatic-cli-0.1.0-dev.20261110.2.tgz
keymatic --version
keymatic login --host https://ig.keymatic.com.br --escopos ler
keymatic contas list

Requer Node.js 20 ou superior. Linux: sha256sum -c SHA256SUMS. Windows PowerShell: Get-FileHash keymatic-cli-0.1.0-dev.20261110.2.tgz -Algorithm SHA256; compare com o arquivo de somas. Atualize instalando um novo tarball verificado.

keymatic login abre o navegador com o mesmo login da conta Keymatic. No macOS, a sessão fica no Chaves. Nas demais plataformas, fica em um arquivo com permissão 0600 dentro de um diretório 0700. A opção KEYMATIC_ARMAZEM=arquivo também usa esse arquivo no macOS.

Ordem de precedência da credencial: KEYMATIC_API_KEY, depois a opção --api-key, depois a sessão salva.

Servidores: chaves da API Keymatic

Para backend a backend, crie uma chave em Chaves da API Keymatic. O segredo aparece uma única vez: guarde no gerenciador de segredos e carregue em KEYMATIC_API_KEY só no processo que chama a API Keymatic. Se perder, gere outra e revogue a anterior.

Prefixo	Uso
`km_api_`	Chave da API Keymatic de uma conta Instagram. Serve API Keymatic e MCP.
`km_mcp_`	Credencial manual criada para um cliente MCP. Também aceita na API Keymatic.
`km_proj_`	Chave de projeto do onboarding hospedado. Só gerencia conexões; não lê nem escreve dados do Instagram.

Validade de 1 a 365 dias, padrão 90.
Limite próprio de 1 a 60 requisições por minuto, padrão 60.
Cada chave fica presa a uma conta Instagram; não existe conta_id no caminho.
Cookies são ignorados na API Keymatic. Nunca envie a chave ao navegador, a um aplicativo distribuído ou a um prompt.

# KEYMATIC_API_KEY vem do seu gerenciador de segredos
curl https://ig.keymatic.com.br/api/instagram/perfil \
  -H "Authorization: Bearer $KEYMATIC_API_KEY"

Permissões

Permissão	Scope OAuth	Libera
`ler`	`instagram:read`	Perfil, publicações, comentários, métricas, uso e operações. Sempre incluída.
`mensagens`	`instagram:messages`	Leitura do Direct.
`responder`	`instagram:reply`	Respostas públicas e regras automáticas. Responder no Direct exige também `mensagens`.
`moderar`	`instagram:moderate`	Ocultar e reexibir comentários.
`publicar`	`instagram:publish`	Importação de mídia, publicação e cancelamento de agenda.

Permissão da chave, capacidade do plano e permissão da Meta são verificações diferentes. Uma chave com publicar não amplia o que a conta autorizou na Meta.

Revogar

Revogue chaves em Chaves da API Keymatic e sessões do navegador ou do CLI em Console → Sessões e apps autorizados. A revogação vale para a API Keymatic, MCP e o worker antes do próximo envio. Sair de todas as sessões ou trocar a senha também encerra o console.