Crie uma chave de API e escolha as permissões
Crie uma chave de API da CodeQR em Configurações → Chaves de API, escolha Acesso Total, Somente Leitura ou Restringido, copie uma vez, veja o uso e troque.
Uma chave de API é o segredo que um programa, script ou ferramenta de automação envia para agir no seu workspace. Este guia cria uma chave com as menores permissões que a tarefa precisa, mostra onde a chave aparece (uma única vez) e como conferir, trocar ou revogar depois.
Disponibilidade
- Plano: todos os planos, inclusive o Free. O plano define o limite de requisições por minuto da chave: Free 60, Starter 100, Pro 500, Business 1.000, Scale 10.000.
- Onde: Configurações → Configurações do Desenvolvedor → Chaves de API (título da página Chaves de API do Projeto). Qualquer membro do workspace pode criar, editar e apagar chaves.
Antes de começar
- A chave pertence ao workspace em que você a cria. Ela não alcança outro workspace e não pode ser movida.
- Decida quem será o dono. Você vincula a chave ao seu usuário; se você for removido do workspace, a chave para de funcionar. Máquina cria um membro-robô e vincula a chave a ele, então a chave sobrevive à saída de pessoas.
- Decida o que ela precisa. Ler analytics não pede escrita; um cenário do Zapier que só cria links não precisa de domínios nem de webhooks.
- Você verá a chave completa uma única vez. Deixe o gerenciador de senhas ou o cofre de segredos aberto.
Passos
- Abra Configurações → Chaves de API e clique em Criar.
- Em Adicionar Nova Chave de API, escolha Você ou Máquina. As dicas explicam: a chave Você fica ligada à sua conta e é apagada se você for removido do projeto; a chave Máquina cria um membro-robô no projeto e não é apagada se você sair.
- Digite um Nome que diga onde a chave vai morar — a ferramenta ou o servidor, não a pessoa (
Automação do Zapier,Sincronia da planilha,Backend produção). - Em Permissões, escolha: - Acesso Total — acesso completo a todos os recursos. - Somente Leitura — Esta chave de API terá acesso somente leitura a todos os recursos. É o padrão. - Restringido — Esta chave de API terá acesso restrito a alguns recursos; aí escolha Nenhum, Read ou Write por recurso: Links, QR Codes, Pages, Tags, Folders, Domains, Projects, Analytics (só Read), Conversions (só Write), Webhooks. Os nomes dos recursos e as opções Read/Write aparecem em inglês. Write sempre inclui Read.
- Clique em Criar chave de API.
- Em Chave da API Criada, copie a chave pelo ícone de copiar e guarde. O diálogo avisa: Por razões de segurança, mostraremos a chave apenas uma vez. Por favor, copie e guarde em um local seguro. Depois clique em Concluído.
A chave começa com codeqr_ e tem 31 caracteres. Na lista ela aparece mascarada (cod...W4TN) com o selo da permissão, a data de criação e Último uso.
Gerencie a chave depois
- Último uso troca de Never para um tempo relativo depois da primeira requisição bem-sucedida — um jeito rápido de ver se uma integração está viva.
- Clique em ⋮ na linha para Editar Chave de API (só nome e permissões — o segredo nunca muda) ou Excluir Chave de API. Excluir abre Excluir chave de API — Isso excluirá permanentemente a chave API e revogará todo o acesso à sua conta. Você tem certeza que quer continuar? — com Confirmar exclusão; a partir daí, toda requisição com aquela chave responde
401.
- Para trocar uma chave: crie uma nova com as mesmas permissões, aponte a ferramenta para ela, confirme que Último uso anda na chave nova e apague a antiga. Não existe botão de regenerar.
- Chaves criadas por integrações: ao ativar Zapier, Make, IFTTT ou outra integração OAuth, ela aparece nesta lista com o nome da integração. Apagar essa chave quebra a integração; desinstale a integração em Configurações → Integrações.
- O que uma chave nunca faz: gerenciar chaves de API, apps OAuth ou integrações. Isso fica no painel.
Faça o mesmo pela API
Não é possível, por desenho — chaves são criadas, editadas e apagadas só no painel. Todo o resto desta série funciona com a chave que você acabou de criar:
curl https://api.codeqr.io/links?pageSize=1 \ -H "Authorization: Bearer codeqr_••••••••••••••••••••••••"
Verifique se funcionou
- Rode a requisição acima. Um
200com um array JSON (possivelmente vazio) significa que a chave é válida e lê links. - Atualize Chaves de API: Último uso agora mostra um horário.
- Tente escrever com uma chave somente leitura para ver a trava:
POST /linksresponde403com The provided key does not have the required permissions for this endpoint in the project '…'. Having the permission 'links.write' would allow this request to continue.
Solução de problemas
Fechei o diálogo e não consigo ver a chave de novo
O texto completo é mostrado uma única vez. Apague a chave e crie outra; a lista só mostra a forma mascarada.
A chave funciona no meu terminal, mas a ferramenta diz "Unauthorized: Invalid API key."
A chave foi colada com um espaço ou quebra de linha, ou uma chave de outro workspace foi usada. Chaves são presas ao workspace; a URL da requisição não tem workspace, então uma chave errada aponta em silêncio para o workspace errado ou é rejeitada. Crie a chave dentro do workspace em que a ferramenta deve escrever.
A ferramenta pede "workspace ID", "project slug" ou "team"
A chave já identifica o workspace; projectSlug e projectId na query string são ignorados para chaves de API. Deixe esses campos vazios ou, se forem obrigatórios na ferramenta, use o slug do workspace que aparece na URL do painel.
Algumas opções Write não aparecem quando um membro cria a chave
Domains → Write, Projects → Write, Conversions → Write e Webhooks → Write são permissões só de proprietário. Uma chave nunca faz mais do que quem a criou, então a chave de um membro recebe no máximo o que um membro pode fazer.
A chave que dei a um prestador continua funcionando depois que ele saiu
Só chaves criadas como Você por aquela pessoa são apagadas quando ela é removida. Chaves Máquina ficam. Revise Chaves de API e apague o que deve sair.