# Autenticação na API: como usar a chave de API (X-API-Key) > Como gerar e usar chaves de API do Bot do Afiliado, autenticar com o header X-API-Key e revogar ou excluir chaves no painel. Requer o módulo Conexão IA e API. - URL: https://botdoafiliado.com/docs/api/autenticacao/ - Publicado em: 2026-05-29 - Atualizado em: 2026-11-08 - Índice da documentação para IA: https://botdoafiliado.com/llms.txt A API usa **chaves de API** geradas no painel. Cada chave tem o formato `bk_.` e é enviada no header **`X-API-Key`**. O recurso exige o módulo **Conexão IA e API** ativo. ## Como chegar Menu → **Configurar** → **API e IA (MCP)**. A tela tem três abas: **Chaves de API**, **Script do site** e **IA (MCP)**. Acima das abas fica o **ID do bot**, com o botão de copiar. Use onde a integração pedir `bot_id`. A chave de API já identifica o bot sozinha, então o ID só serve em integração que peça o ID explícito. ## Gerar uma chave 1. Ative o **[módulo Conexão IA e API](/docs/planos/modulos/)**. 2. Em **API e IA (MCP)**, abra a aba **Chaves de API**. 3. No card **Criar chave de API**, dê um **nome** (opcional), escolha o **nível de permissão** e clique em **Criar**. 4. **Copie a chave completa** no card que aparece ("Chave criada no nível ... (copie agora)"). Se precisar dela de novo, use **Mostrar** na linha da chave (só o dono e os admins da organização, e só em chaves criadas a partir de 16/10/2026). O botão **Conectar IA (MCP) →** do card da chave criada leva à aba **IA (MCP)**, já com a chave nos comandos. Veja **[O que é o MCP](/docs/ia/o-que-e-mcp/)**. Aba Chaves de API: o card Criar chave de API com Nome (opcional), o nível Padrão e o botão Criar; embaixo, a lista de chaves com Nome, Chave e Mostrar, o seletor de Nível, a Origem padrão com Trocar ou Definir, e Revogar e Excluir em cada linha ## A lista de chaves | Coluna | O que mostra | |---|---| | **Nome** | O nome da chave, quando foi criada e quando foi usada pela última vez ("nunca usada", "usada há 2 h"). Chave revogada ganha o selo **Revogada**. | | **Chave** | O prefixo da chave e o botão **Mostrar**, que abre a chave inteira (com **Ocultar** e copiar). Em chave criada antes de 16/10/2026, o painel avisa que não dá para mostrar de novo. | | **Nível** | Seletor com **Leitura**, **Padrão** e **Total**. Trocar vale na chamada seguinte. | | **Origem padrão** | O destino que vale quando a chamada não diz onde o link vai. **Definir** ou **Trocar** abre o tipo (**Grupo**, **Canal**, **Site** ou **Post**) e o id. | | Última coluna (sem título) | **Revogar** e **Excluir**. | Você pode ter várias chaves, uma por integração ou sistema, e revogar cada uma separadamente. ### Origem padrão A **Origem padrão** vale quando a chamada à API não manda `chat_id` nem `origem`: é como se mandasse esta origem. Serve para a integração que só converte e não sabe dizer o destino. Grupo e canal do Telegram usam o id do chat (ex.: `-1001234567890`); site usa o domínio (ex.: `meusite.com.br`); post usa um nome curto (ex.: `black-friday`). O id tem até 64 caracteres, só letras, números e `_ : . -`. O que vier no pedido ganha da origem padrão. Detalhes em **[convert-links](/docs/api/convert-links/)**. ## Usar nas chamadas ```bash curl -X POST "https://botdoafiliado.com/api/v1/convert-links" \ -H "content-type: application/json" \ -H "X-API-Key: bk_xxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -d '{"url":"https://www.aliexpress.com/item/100500..."}' ``` ## Níveis de permissão Cada chave é criada com um **nível**, escolhido no painel. Ele limita o que aquela chave pode fazer na API (e nas ferramentas MCP, que passam pelos mesmos endpoints): | Nível | Vale para | Endpoints | |---|---|---| | **Leitura** (`read`) | Consulta que **não** devolve link de afiliado nem gasta cota do marketplace | `/api/v1/coupons` (GET), `/coupons/categories`, `/templates` (GET), `/showcase/items` (GET), `/bot`, `/userbot/config` (GET), `/userbot/history`, `/userbot/preview-rules` | | **Padrão** (`write`) | Leitura + operação do dia a dia | tudo de Leitura + `/convert`, `/convert-links`, `/product`, `/product/shipping`, `/product/history`, `/execute`, `/chat`, `/search-products`, `/amazon-prices`, `/promo-card`, `/watermark`, `/showcase/items` (POST e DELETE) | | **Total** (`admin`) | Tudo, incluindo importar e apagar cupom, editar os textos do bot e configurar o Puxador | tudo de Padrão + `/coupons/ingest`, `/coupons/ingest-plugins`, `/coupons/{id}` (DELETE), `/coupons/{id}/activate`, `/templates` (POST), `/userbot/config` (POST) | Os endpoints `/userbot/*` são os do **[Puxador](/docs/telegram/userbot/)**. **Todo endpoint que devolve link de afiliado é Padrão**, mesmo parecendo consulta: `/product`, `/search-products` e `/amazon-prices` geram ou entregam link com a sua tag, que é exatamente o que uma chave de Leitura não deve fazer. Leitura fica com o que só informa: frete, histórico de preço, cupons e templates já cadastrados. Ao conectar a IA por **MCP com login (OAuth)**, sem colar chave, o nível vem do seu papel na organização: **dono e admin → Total**, **postador → Padrão**. Uma chamada acima do nível da chave responde **403** com `insufficient_scope`: ```json { "success": false, "error": "insufficient_scope" } ``` O nível é escolhido na criação e **pode ser trocado depois**: na lista de chaves, a coluna **Nível** é um seletor. Trocar **não rotaciona o segredo**: a mesma chave continua valendo, com o novo nível já na chamada seguinte. Chaves criadas antes desta mudança continuam em **Total** até você rebaixá-las. Use o menor nível que resolve: a chave que só lê preço no seu site não precisa poder apagar cupom. ## Revogar ou excluir Na aba **Chaves de API**, cada chave tem duas ações: - **Revogar**: desativa a chave (efeito imediato), mas **mantém o registro** na lista (útil para auditoria e histórico). Não dá para reativá-la. Integrações que usam a chave (MCP, API, IA) param na hora. - **Excluir**: **remove a chave de vez** da lista. Chaves já revogadas também podem ser excluídas para limpar a lista. ## Segurança - A chave completa **não fica armazenada** em texto puro: a API confere a chave por um hash, e a cópia que o **Mostrar** abre fica cifrada. Na lista, o painel mostra só o **prefixo**, e cada Mostrar fica no log de auditoria. - Crie a chave no **menor nível** que atende à integração (ver [Níveis de permissão](#níveis-de-permissão)). - **Revogue ou exclua** chaves comprometidas na aba Chaves de API (efeito imediato). - Nunca exponha a chave no front-end; use-a apenas no servidor. Próximo: faça sua primeira conversão em **[convert-links](/docs/api/convert-links/)**. ## Perguntas frequentes ### Dá para criar uma chave de API do Bot do Afiliado só de leitura? Sim. Cada chave tem um nível, Leitura (consulta que não gera link), Padrão (consulta e gera link de afiliado) ou Total (inclui cupom, textos do bot e Puxador). Chamada acima do nível da chave responde 403 com o erro insufficient_scope. ### Como mudar o nível de uma chave de API já criada no Bot do Afiliado? Na aba Chaves de API, troque o valor na coluna Nível da chave. Vale na chamada seguinte e não muda o valor da chave, então a integração continua funcionando sem trocar o segredo. ### A chave de API (X-API-Key) do Bot do Afiliado aparece de novo depois de criada? Sim, para o dono e os admins da organização. Na aba Chaves de API, use Mostrar na linha da chave. Vale para chaves criadas a partir de 16/10/2026. As anteriores aparecem só na criação, e para ter uma que dá para ver de novo é preciso gerar outra. ### Como revogar ou excluir uma chave de API do Bot do Afiliado no painel? Na aba Chaves de API, use Revogar para desativar a chave (ela continua na lista, desativada) ou Excluir para removê-la de vez. Nos dois casos a chave deixa de funcionar imediatamente. ### Preciso enviar bot_id junto com a X-API-Key nas chamadas da API REST? Não. O bot é sempre identificado pela X-API-Key; o campo bot_id, se enviado, é ignorado, e a chave é obrigatória. O ID do bot aparece no topo da tela API e IA (MCP) para as integrações que pedem esse ID explícito. Para uso direto no navegador (sites e widgets), use uma Embed Key travada por domínio, não a X-API-Key.