As permissões das chaves API decidem o que uma chave divulgada pode estragar. Numa ferramenta de links, o padrão seguro é uma chave presa a um único workspace, limitada ao papel mais baixo que faz o trabalho, guardada como hash com pepper, com limite de taxa próprio e com data de expiração. Uma chave que só cria links não tem nada que mexer em webhooks, membros ou faturamento, e nunca deve abrir um endpoint de administração. Isso é privilégio mínimo, e quase tudo se resume a escolhas feitas nos trinta segundos que demora criar a chave.
Li muitas configurações de automação no último ano e o padrão se repete: alguém cola a sua própria chave todo-poderosa no n8n numa sexta-feira à tarde, funciona, e ninguém volta a pensar nisso até essa pessoa sair ou a exportação do fluxo ir parar a uma pasta compartilhada. O resto deste artigo explica como funcionam os scopes e os papéis das chaves API num produto de links curtos, o que cada papel pode realmente fazer e como entregar uma chave a uma ferramenta de automação sem entregar o workspace.
Complementa a nossa lista de segurança de encurtadores de URL, mais ampla, que cobre análise, assinatura de webhooks e registros de auditoria em toda a plataforma. Este se foca na chave em si.
O que significam as permissões de chaves API numa ferramenta de links
A API de uma ferramenta de links toca em mais do que links. O mesmo token que cria go.example.com/spring-sale pode, consoante as suas permissões, ler estatísticas de cliques, adicionar um domínio personalizado, convidar um membro ou registrar um webhook que envia todos os eventos para um servidor externo. Este último me assusta. Um webhook é um fluxo de dados permanente que quem o cria pode apontar para o servidor que quiser, e ninguém da sua equipe repararia necessariamente durante semanas.
Assim, as permissões têm três eixos. Onde funciona a chave (que conta ou workspace)? O que pode fazer aí (ler, escrever, administrar)? E durante quanto tempo e a que velocidade? A definição de privilégio mínimo no glossário do NIST (acesso em 2026-10-24) diz que cada entidade recebe as autorizações mínimas de que precisa para desempenhar a sua função, e os três eixos fazem parte disso. Uma chave só de leitura que nunca expira e não tem limite de taxa continua sobreprivilegiada no tempo.
Chaves API por workspace: uma chave, um workspace
No Elido, cada chave é criada dentro de um workspace e fica lá. Se chamar com ela os endpoints de outro workspace, recebe um 404, a mesma resposta que para um workspace que não existe, pelo que uma chave nem sequer consegue confirmar que os outros workspaces existem.
Isto importa mais do que parece. As agências e as equipes maiores costumam pertencer a cinco ou dez workspaces. Se uma chave pessoal herdasse tudo o que o seu criador alcança, um único token divulgado num projeto de um cliente abriria todos os clientes. As chaves API por workspace reduzem o raio de impacto a um único workspace.
A chave fica também limitada ao papel escolhido na criação e nunca excede o papel atual do seu criador. O acesso efetivo é o mais baixo dos dois. Despromova a editor o admin que criou uma chave. A chave desce com ele. As permissões personalizadas atribuídas a esse membro também são ignoradas sempre que o papel da chave for o mais baixo, porque descrevem a pessoa, não a chave.
Chaves API por papel: o que cada papel pode fazer
As chaves do Elido usam os mesmos quatro papéis que as pessoas: viewer, editor, admin e owner. Escolhe um ao criar a chave; se o omitir, a chave assume editor, que cobre a tarefa habitual de automação de criar links e ler estatísticas sem alcance de administração.
Eis o que isso significa na prática para as coisas em que as integrações costumam mexer.
| Papel | Links e campanhas | Estatísticas | Webhooks | Domínios, membros, chaves |
|---|---|---|---|---|
| viewer | Só leitura | Ler, iniciar tarefas de exportação CSV | Listar endpoints | Ver domínios e membros |
| editor | Criar, editar, apagar, criar em massa | Ler, iniciar tarefas de exportação CSV | Listar endpoints | Ver domínios e membros |
| admin | Tudo o que o editor pode | Mais configuração de exportação de dados S3, relatórios agendados por e-mail | Criar, alterar, repetir | Gerenciar domínios, membros, chaves |
| owner | Tudo | Tudo | Tudo | Tudo |
Um painel de relatórios que leva contagens de cliques para uma ferramenta de BI precisa de viewer. Uma tarefa do Google Sheets que cria links de campanha precisa de editor. Quase nada na automação diária precisa de admin, e eu trataria uma chave owner como um mau sinal: o owner existe para as pessoas que gerem o workspace, e não consigo pensar em nenhuma tarefa de automação que o exija.
Vale a pena conhecer dois limites. Só admins e owners têm a permissão api_keys.manage, pelo que uma chave viewer ou editor não pode listar nem revogar chaves. E criar uma chave, ou alterar o seu limite de taxa, exige uma pessoa com sessão iniciada: uma chave API de qualquer papel recebe um 403 ("this action requires an interactive session"). Uma chave admin divulgada não consegue criar uma substituta sem expiração. Continua a poder listar e revogar chaves. E nenhuma chave de qualquer papel alcança a API de administração da plataforma. Essa superfície recusa a autenticação por chave API com um 403 e a mensagem "admin access requires an interactive session". Uma chave serve para uma integração do workspace, e é só isso que abre.
Porque a gestão de webhooks exige uma chave admin
É esta que surpreende as pessoas. Ler a lista de endpoints de webhook é permitido a qualquer membro, incluindo chaves viewer. Mas criar um endpoint, mudar para onde aponta ou repetir uma entrega exige a permissão workspace.edit, que só admin e owner têm.
A razão é o problema do fluxo permanente referido atrás. Um editor pode criar mil links e você repara. Um editor que pudesse acrescentar um webhook abrangente apontado para o seu próprio servidor passaria a receber, em silêncio, todos os eventos de links. Por isso as alterações a webhooks ficam com as mesmas pessoas que podem alterar as configurações do workspace.
Na prática, configure os webhooks uma só vez, à mão, como admin no painel. Depois dê à automação que os consome uma chave editor ou viewer para as suas chamadas à API. Se está conectando webhooks de eventos de links ao Slack ou a um CRM, o lado receptor nem precisa de uma chave do Elido; precisa do segredo de assinatura para verificar os payloads.
Quer uma prova antes de conectar o que quer que seja? Crie um workspace gratuito, gere uma chave viewer e uma chave editor e experimente a mesma chamada de escrita com cada uma. O 403 na chave viewer lhe diz mais do que qualquer tabela.
Como as chaves são guardadas: pepper, hash e prefixo
Um token tem o aspeto elido_ seguido de 52 caracteres base32, gerados a partir de 32 bytes aleatórios. Vê-o completo exatamente uma vez, na resposta à chamada de criação. Depois disso, desaparece do nosso lado para sempre.
O que guardamos é um HMAC-SHA256 do token, com chave num pepper do servidor que vive na configuração da aplicação, não na base de dados. Em cada pedido, o token Bearer recebido (o esquema definido na RFC 6750, acesso em 2026-10-24) passa pelo mesmo hash e é procurado por hash. Assim, um despejo roubado da base de dados é uma lista de hashes que ninguém consegue verificar sem o pepper. Sem pepper, sem arranque: o serviço de produção se recusa a iniciar sem um definido.
Para o seu registro, guardamos os primeiros oito caracteres a seguir a elido_ como prefixo de apresentação, e a página de chaves API mostra esse prefixo junto ao nome da chave, ao papel, à data de criação, à expiração, à hora da última utilização e ao último IP utilizado, além das contagens totais e de pedidos falhados. Quando uma chave aparece num registro algures, o prefixo lhe diz qual é. Ninguém precisa de ver o segredo completo.
Limites de taxa, expiração e rotação de chaves API
Cada chave tem o seu próprio token bucket, separado do limite por workspace, para que um fluxo descontrolado não consuma o orçamento de tudo o resto. Um admin com sessão iniciada pode substituir a taxa de uma única chave de 1 a 10 000 pedidos por segundo e o seu burst de 1 a 20 000, ou limpar a substituição para voltar à padrão. Acima do limite, a chave recebe um 429 com Retry-After: 1 e X-RateLimit-Scope: api_key, para que a sua lógica de repetição distinga o limite de uma chave do limite de um workspace. O guia de limites de taxa e idempotência explica como recuar corretamente.
A expiração é opcional e definida na criação como um carimbo de data/hora RFC 3339. Passada essa data, a chave simplesmente deixa de corresponder. A revogação é um único DELETE. Também é idempotente.
Não há um único botão de "rodar", e não me faz falta. A rotação são três passos:
- Crie uma chave nova com o mesmo papel e uma expiração nova.
- Troque-a no armazém de credenciais da ferramenta e confirme que uma chamada tem sucesso.
- Revogue a chave antiga e verifique na lista que a hora da última utilização deixou de avançar.
Cada passo fica no registro de auditoria do workspace: api_key.created com o nome e o papel, api_key.revoked e api_key.rate_limit_set para as substituições. Uma verificação em segundo plano corre também de cinco em cinco minutos e assinala qualquer chave com mais de 1000 pedidos em que mais de 30% falharam. O sinalizador vai para o registro de auditoria e para a chave. Sem revogação automática. Matar uma chave é uma decisão humana, porque uma rajada de 404 é tantas vezes um fluxo quebrado como um atacante.
Entregar chaves API de privilégio mínimo ao n8n, Make e Zapier
As plataformas de automação são onde as chaves vão para ser esquecidas. Ficam num armazém de credenciais, são copiadas para o JSON exportado dos fluxos e sobrevivem à pessoa que as configurou. Dois hábitos ajudam:
- Uma chave por ferramenta e por família de fluxos, com o nome dela ("n8n: folhas de campanha"). Revogá-la quebra então exatamente uma coisa, e o registro de auditoria diz qual ferramenta fez o quê.
- Editor para tudo o que cria links, viewer para tudo o que só lê, e uma data de expiração em ambos.
A lista fica por aqui; o resto é juízo. A Secrets Management Cheat Sheet da OWASP (acesso em 2026-10-24) é uma boa leitura sobre como manter tokens fora de registros e exportações, que é onde as chaves de automação costumam vazar.
Para a configuração específica de cada ferramenta, o guia do encurtador de URL no n8n põe a chave numa credencial Header Auth, e a comparação Make vs IFTTT vs n8n vs Zapier mostra onde cada plataforma a guarda. O Zapier se conecta através do mesmo token, segundo o guia de automação com Zapier. Para CI ou qualquer coisa que deva sobreviver à saída de uma pessoa, um usuário máquina é a melhor opção: uma conta de serviço com o seu próprio token, separada da chave de qualquer humano. Tal como as chaves, os usuários máquina são criados por um admin com sessão iniciada, nunca por um token.
E a razão pela qual uma chave nunca deve abrir endpoints de administração é precisamente esta entrega. Quando um token está numa ferramenta de terceiros, qualquer pessoa com acesso de edição aos fluxos dessa ferramenta pode usá-lo. Está confiando em todos do lado deles, não apenas nos seus.
Tokens por scope: planejados, não ativos
Os papéis são grosseiros de propósito, e por vezes demasiado grosseiros. Uma chave editor que só cria links também as pode apagar, porque apagar faz parte do papel de editor. A solução são tokens por scope, como links:write ou analytics:read vinculados diretamente a uma chave, por cima dos papéis.
Isso está no nosso roadmap e não foi lançado. Hoje, as permissões de uma chave são o seu workspace mais o seu papel, e nada mais fino. Se precisa agora de controle mais apertado, as duas alavancas são um papel mais baixo e uma expiração curta, mais chaves separadas por tarefa para que o raio de impacto de cada uma seja pequeno. O guia rápido da API e a referência da API e dos SDKs mostram o modelo atual de chaves em código funcional, e as equipes que também querem controle ao nível da identidade podem ler sobre SCIM e SSO para ferramentas de marketing.
Leia o artigo de referência: a lista de segurança de encurtadores de URL cobre os controles ao redor da chave, da análise de URLs às listas de IPs permitidos.
Relacionado no blog
Perguntas frequentes
O que são permissões de chaves API?
São o conjunto de ações que uma chave pode executar numa API: que recursos pode ler, quais pode alterar e em que conta. No Elido, as permissões de uma chave vêm do workspace onde foi emitida e do papel escolhido na criação, pelo que a mesma chave não pode agir noutro workspace nem acima desse papel.
O que é o privilégio mínimo nas chaves API?
Significa que cada chave recebe o menor conjunto de permissões de que a sua tarefa precisa e nada mais. Um painel que só lê contagens de cliques recebe uma chave viewer, um fluxo que cria links recebe uma chave editor, e as chaves admin ficam para a tarefa rara que gere webhooks, domínios ou membros. Uma chave divulgada só consegue então fazer o que essa tarefa fazia.
Qual é a diferença entre scopes e papéis nas chaves API?
Um scope é uma permissão estreita, como links:write, vinculada diretamente a um token, enquanto um papel é um pacote nomeado de permissões, como editor. Os papéis são mais fáceis de raciocinar; os scopes são mais finos. As chaves do Elido usam hoje papéis do workspace, e os tokens por scope estão planejados por cima deles, mas ainda não estão ativos.
Com que frequência se devem rodar as chaves API?
A orientação comum é de 30 a 90 dias, e de imediato sempre que sai alguém que viu a chave, a chave aparece num registro ou o seu tráfego parece estranho. Definir uma data de expiração na criação transforma esse calendário numa paragem obrigatória, em vez de um lembrete que as pessoas ignoram.
Uma chave API pode acessar a endpoints de administração?
No Elido, não. A API de administração da plataforma só aceita uma sessão interativa com login e responde a uma chave API com um 403, seja qual for o papel de quem a criou. As configurações do workspace que exigem direitos de admin continuam acessíveis, mas só por uma chave criada com o papel admin ou owner.
Como devem ser guardadas as chaves API do lado do fornecedor?
Nunca em texto simples. O fornecedor deve guardar um hash com chave do token e mostrar-lhe depois apenas um prefixo curto, para que uma cópia da base de dados, por si só, não possa ser usada para chamar a API. O Elido aplica a cada token um HMAC-SHA256 com um pepper do servidor e mostra o token completo exatamente uma vez.
Experimente Elido
Cole uma URL, obtenha um link curto
Sem cadastro. O link vive 30 dias. Cadastre-se para mantê-lo para sempre.
Sem registo. Crie uma conta grátis e obtenha 50 links por mês.