Quando você cria uma chave de API da conta no Provedly, toma uma única decisão: Read only ou Read and write. É uma escolha pequena que define o quanto um assistente de IA ou um script pode fazer com a sua conta, e vale acertá-la no primeiro dia em vez de depois de alguma surpresa.
O que cada nível permite
| Ação | Somente leitura | Leitura e escrita |
|---|---|---|
| Ver plano, limites e uso | Sim | Sim |
| Listar sites, widgets e barras | Sim | Sim |
| Ler estatísticas (impressões, cliques, pedidos) | Sim | Sim |
| Obter o snippet de instalação | Sim | Sim |
| Pausar ou retomar um widget | Não | Sim |
| Criar uma barra, editá-la, pausá-la ou retomá-la | Não | Sim |
| Adicionar um registro | Não | Sim |
| Marcar um registro como verificado | Não | Não |
A última linha não é erro de digitação. Nenhuma chave consegue marcar nada como verificado, em nenhum nível. A verificação vem apenas de webhooks assinados do Stripe, Shopify e WooCommerce, e a API não tem como contornar isso. Registros adicionados com uma chave de escrita mantêm a origem API, levam o rótulo visível "Imported" no widget e nunca mostram a marca Verified. Por que o seu assistente não consegue verificar uma compra explica o raciocínio.
A mesma tabela vale seja a chave usada pela API REST ou pelo servidor MCP. Uma chamada de ferramenta é uma chamada de API com uma fachada mais amigável.
Qual escolher
Uma regra simples: dê a cada chave o mínimo de que ela precisa para fazer o seu trabalho, e crie uma segunda chave quando surgir um segundo trabalho.
Relatórios e perguntas. Uma revisão semanal de estatísticas, um script de dashboard, um assistente a quem você pergunta "como foi a semana passada": somente leitura. Nada disso precisa alterar coisa alguma, e uma chave somente leitura vazada deixa um estranho ler os seus números, mas não mexer no seu site.
Gerenciar campanhas pelo chat. Se você quer dizer "pause a barra de Black Friday" ou "crie a contagem regressiva do lançamento" e ver isso acontecer, o assistente precisa de leitura e escrita. É essa a ideia do fluxo de Black Friday pelo chat.
Backends adicionando compras. Um servidor que envia registros precisa de leitura e escrita. Dê a ele uma chave própria, com o nome do serviço, para poder trocá-la sem mexer em mais nada.
Freelancers e agências. Uma chave por pessoa, com o nome dela. Quando o trabalho terminar, revogue-a. O lado das agências está em gerenciando vários sites de clientes.
Proteções que existem seja qual for a chave
Mesmo uma chave de leitura e escrita funciona dentro das mesmas regras do painel, o que limita o estrago dos erros.
- Os limites do plano valem. Retomar um widget ou ativar uma barra além do limite do seu plano é recusado.
- Barras novas começam pausadas. Uma barra criada pela API ou pelo MCP não aparece para os visitantes até alguém ativá-la numa segunda etapa. Um prompt mal entendido ou um script com bug produz um rascunho pausado, não um banner no ar.
- Nada vira verificado. Explicado acima.
- A revogação é imediata. Revogue uma chave em Settings e a próxima requisição com ela falha.
Cuidando das chaves
As chaves começam com provedly_ e são mostradas uma única vez, na criação. O Provedly não as mostra de novo, então não há o que recuperar; uma chave perdida é revogada e substituída.
A maioria dos problemas vem de onde as chaves vão parar. Alguns lugares para ficar de olho:
Arquivos de configuração do cliente MCP. O Claude Code e o Cursor guardam as configurações de servidores em arquivos de configuração. Se você adicionar o servidor no nível do projeto e o projeto estiver no git, confira antes de fazer commit. O guia do Claude Code e o guia do Cursor mostram onde a chave fica guardada.
Histórico do shell. Coloque a chave numa variável de ambiente ou num gerenciador de segredos em vez de colá-la num comando curl que você vai encontrar depois no histórico.
Código do navegador. Uma chave em JavaScript do lado do cliente é pública. A API é para servidores, terminais e ferramentas de IA, nunca para um script rodando na sua loja. O próprio script do widget não precisa de chave.
Conversas no chat. Não cole a chave no chat com o seu assistente. Ela vai no cabeçalho Authorization da configuração do servidor, de onde o cliente a envia sem que o modelo precise vê-la.
Se uma chave vazar
Revogue-a em Settings, depois crie uma nova e atualize onde a antiga era usada. Em seguida, veja o que mudou: a lista de barras e widgets mostra o estado atual, e qualquer registro adicionado pela API aparece com a origem API na aba Data do widget, então é fácil identificá-los e removê-los. Como registros da API nunca podem ser verificados, uma chave vazada não consegue colocar compras verificadas falsas na sua página de verificação.
Perguntas frequentes
Posso mudar uma chave de somente leitura para leitura e escrita?
Crie uma nova chave com o nível que quiser e revogue a antiga. Manter o nível fixo por chave deixa claro o que cada uma pode fazer.
Várias ferramentas devem compartilhar uma chave?
Funciona, mas chaves separadas dão menos dor de cabeça. Com uma chave por ferramenta ou pessoa, a tela de API keys mostra quem tem acesso, e revogar uma não quebra as outras.
O widget do meu site usa uma dessas chaves?
Não. A tag de script nas suas páginas usa um token público do widget e não precisa de segredo. As chaves de API da conta são só para a API REST e o servidor MCP.
As chaves estão disponíveis em todos os planos, inclusive o Free. Crie uma conta para gerar a sua primeira.