Permissões de chave de API decidem o que uma chave vazada consegue quebrar. Em uma ferramenta de links, o padrão seguro é uma chave vinculada a um único espaço de trabalho, limitada à função mais baixa que realiza o trabalho, armazenada como hash com pepper, limitada por taxa própria e configurada para expirar. Uma chave que só cria links não tem motivo para tocar em webhooks, membros ou cobrança, e nunca deve abrir um endpoint administrativo. Isso é privilégio mínimo, e a maior parte dele se resume às escolhas que você faz nos trinta segundos necessários para criar a chave.
Li muitas configurações de automação no último ano, e o padrão se repete: alguém cola sua própria chave todo-poderosa no n8n em uma sexta-feira à tarde, funciona, e ninguém pensa mais nisso até essa pessoa sair ou a exportação do fluxo de trabalho parar em um armazenamento compartilhado. O resto deste post cobre como escopos e funções de chave de API funcionam em um produto de links curtos, o que cada função realmente pode fazer e como entregar uma chave a uma ferramenta de automação sem entregar o espaço de trabalho inteiro.
Ele acompanha nossa lista de verificação mais ampla de segurança para encurtador de URL, que cobre varredura, assinatura de webhook e logs de auditoria na plataforma inteira. Este aqui aproxima a lente da própria chave.
O que permissões de chave de API significam em uma 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, dependendo de suas permissões, ler análises de cliques, adicionar um domínio personalizado, convidar um membro ou registrar um webhook que envia todos os eventos para um servidor externo. Esse último ponto me preocupa. Um webhook é um feed de dados permanente que quem o cria pode apontar para qualquer servidor que quiser, e ninguém na sua equipe necessariamente perceberia por semanas.
Então as permissões têm três eixos. Onde a chave funciona (qual conta ou espaço de trabalho)? O que ela pode fazer ali (ler, escrever, administrar)? E por quanto tempo, e em que velocidade? A definição de privilégio mínimo do NIST se resume a conceder apenas o acesso de que uma tarefa precisa, e os três eixos fazem parte disso. Uma chave com direitos somente leitura que nunca expira e não tem limite de taxa ainda tem privilégios demais no tempo.
Chaves de API com escopo de espaço de trabalho: uma chave, um espaço de trabalho
No Elido, toda chave é emitida dentro de um espaço de trabalho e fica ali. Chame endpoints de qualquer outro espaço de trabalho com ela e você recebe um 404, a mesma resposta de um espaço de trabalho que não existe, então uma chave nem sequer consegue confirmar que outros espaços de trabalho existem.
Isso importa mais do que parece. Agências e equipes maiores muitas vezes pertencem a cinco ou dez espaços de trabalho. Se uma chave pessoal herdasse tudo que seu criador consegue acessar, um token vazado de um projeto de um cliente abriria todos os clientes. Chaves de API com escopo de espaço de trabalho reduzem o raio de impacto a um espaço de trabalho.
A chave também é limitada pela função escolhida quando foi criada, e nunca ultrapassa a função atual de seu criador. O acesso efetivo é o menor dos dois. Rebaixe para editor o admin que criou uma chave. A chave cai junto. Permissões personalizadas anexadas àquele membro também são descartadas sempre que a função da chave é a menor, porque elas descrevem a pessoa, não a chave.
Chaves de API baseadas em função: o que cada função pode fazer
As chaves do Elido usam as mesmas quatro funções que as pessoas: viewer, editor, admin e owner. Você escolhe uma ao criar a chave; se deixar em branco, a chave usa editor por padrão, o que cobre o trabalho comum de automação de criar links e ler análises sem nenhum alcance administrativo.
Veja como isso fica na prática para as coisas em que integrações costumam tocar.
| Função | Links e campanhas | Análises | Webhooks | Domínios, membros, chaves |
|---|---|---|---|---|
| viewer | Somente leitura | Ler, executar exportações CSV | Listar endpoints | Ver domínios e membros |
| editor | Criar, editar, excluir, criar em lote | Ler, executar exportações CSV | Listar endpoints | Ver domínios e membros |
| admin | Tudo que editor pode fazer | Mais exportações de dados, relatórios agendados | Criar, alterar, reenviar | Gerenciar domínios, membros, chaves |
| owner | Tudo | Tudo | Tudo | Tudo |
Um painel de relatórios que puxa contagens de cliques para uma ferramenta de BI precisa de viewer. Um trabalho do Google Sheets que emite links de campanha precisa de editor. Quase nada na automação do dia a dia precisa de admin, e eu trataria uma chave owner como um sinal de alerta: owner existe para as pessoas que administram o espaço de trabalho, e não consigo pensar em nenhum trabalho de automação que precise disso.
Vale conhecer dois limites. Apenas admins e owners podem criar, listar ou revogar chaves, então uma chave viewer ou editor não consegue criar para si uma chave com mais poderes. E nenhuma chave, de qualquer função, alcança a API administrativa da plataforma. Essa API recusa autenticação por chave de API diretamente com um 403 e a mensagem "admin access requires an interactive session". Uma chave serve para uma integração de espaço de trabalho, e isso é tudo que ela abre.
Por que o gerenciamento de webhooks precisa de uma chave admin
Esta é a parte que surpreende as pessoas. Ler a lista de endpoints de webhook é permitido para qualquer membro, inclusive chaves viewer. Mas criar um endpoint, alterar para onde ele aponta ou reenviar uma entrega exige a permissão workspace.edit, que só admin e owner têm.
O motivo é o problema do feed permanente de antes. Um editor pode criar mil links, e você vai perceber. Um editor que pudesse adicionar um webhook abrangente apontado para seu próprio servidor receberia todos os eventos de link dali em diante, silenciosamente. Por isso, alterações de webhook ficam com as mesmas pessoas que podem alterar as configurações do espaço de trabalho.
Na prática, configure webhooks uma vez, manualmente, como admin no painel. Depois dê à automação que os consome uma chave editor ou viewer para suas chamadas de API. Se você está conectando webhooks para eventos de link ao Slack ou a um CRM, o lado receptor não precisa de uma chave do Elido; precisa do segredo de assinatura para verificar cargas úteis.
Quer uma prova antes de conectar qualquer coisa? Crie um espaço de trabalho gratuito, emita uma chave viewer e uma chave editor, e tente a mesma chamada de escrita com cada uma. O 403 na chave viewer diz mais do que qualquer tabela.
Como as chaves são armazenadas: pepper, hash e prefixo
Um token se parece com elido_ seguido por 52 caracteres de base32, gerados a partir de 32 bytes aleatórios. Você vê o token inteiro exatamente uma vez, na resposta à chamada de criação. Depois disso, ele desaparece do nosso lado de vez.
O que mantemos é um HMAC-SHA256 do token, com chave usando um pepper no lado do servidor que vive na configuração da aplicação, não no banco de dados. Em cada solicitação, o token Bearer recebido (o esquema definido na RFC 6750) passa pelo mesmo hash e é procurado pelo hash. Um dump roubado do banco de dados é uma lista de hashes que não podem ser verificados sem o pepper, e o serviço de produção se recusa a iniciar sem um configurado.
Para seus próprios registros, armazenamos os primeiros oito caracteres depois de elido_ como prefixo de exibição. A página de chaves de API mostra esse prefixo ao lado do nome da chave, função, data de criação, expiração, horário do último uso e IP do último uso, além das contagens totais e de falhas de solicitações. Quando uma chave aparece em algum log, o prefixo mostra qual é sem que ninguém precise ver o segredo completo.
Limites de taxa, expiração e rotação de chave de API
Cada chave recebe seu próprio balde de tokens, separado do limite por espaço de trabalho, então um fluxo de trabalho fora de controle não consome o orçamento de todo o resto. Um admin pode substituir a taxa de uma única chave de 1 a 10.000 solicitações por segundo e a rajada dela de 1 a 20.000, ou limpar a substituição para voltar ao padrão. Acima do limite, a chave recebe um 429 com Retry-After: 1 e X-RateLimit-Scope: api_key, para que sua lógica de nova tentativa consiga distinguir um limite da chave de um limite do espaço de trabalho. O guia de limites de taxa e idempotência cobre como aplicar backoff corretamente.
A expiração é opcional e definida na criação como um timestamp RFC 3339. Assim que passa, a chave simplesmente deixa de corresponder. A revogação é um DELETE. Também é idempotente.
Não existe um único botão "rotate", e não sinto falta dele. A rotação tem três passos:
- Crie uma nova chave com a mesma função e uma nova expiração.
- Troque-a no armazenamento de credenciais da ferramenta e confirme que uma chamada funciona.
- Revogue a chave antiga e depois confira na lista se o horário do último uso parou de mudar.
Cada passo entra no log de auditoria do espaço de trabalho: api_key.created com o nome e a função, api_key.revoked e api_key.rate_limit_set para substituições. Uma varredura em segundo plano também roda a cada cinco minutos e sinaliza qualquer chave com mais de 1.000 solicitações em que mais de 30% falharam. O sinalizador vai para o log de auditoria e para a chave. Sem revogação automática. Encerrar uma chave é uma decisão humana, porque uma rajada de 404s é tão frequentemente um fluxo de trabalho quebrado quanto um atacante.
Entregando chaves de API com privilégio mínimo para n8n, Make e Zapier
Plataformas de automação são onde chaves vão para serem esquecidas. Elas ficam em um armazenamento de credenciais, são copiadas para JSONs de fluxo de trabalho exportados e sobrevivem à pessoa que as configurou. Dois hábitos ajudam:
- Uma chave por ferramenta e por família de fluxos de trabalho, nomeada de acordo com ela ("n8n: planilhas de campanha"). Revogá-la quebra exatamente uma coisa, e o log de auditoria diz qual ferramenta fez o quê.
- Editor para qualquer coisa que cria links, viewer para qualquer coisa que apenas lê, e uma data de expiração em ambas.
É só isso para a lista; o resto é julgamento. O guia de bolso de gerenciamento de segredos da OWASP é uma boa leitura sobre manter tokens fora de logs e exportações, que é onde chaves de automação costumam vazar.
Para a configuração específica de cada ferramenta, o guia de encurtador de URL no n8n coloca a chave em uma credencial Header Auth, e a comparação entre Make, IFTTT, n8n e Zapier cobre onde cada plataforma a mantém. O Zapier se conecta pelo mesmo token, conforme o passo a passo de automação com Zapier. Para CI ou qualquer coisa que deva sobreviver à saída de uma pessoa, um usuário de máquina é o melhor encaixe: uma conta de serviço com sua própria função, separada da chave de qualquer pessoa.
E o motivo pelo qual uma chave nunca deve abrir endpoints administrativos é exatamente esse repasse. Depois que um token fica em uma ferramenta de terceiros, qualquer pessoa com acesso de edição aos fluxos de trabalho dessa ferramenta pode usá-lo. Você confia em todos do lado deles, não só do seu.
Tokens por escopo estão planejados, não ativos
Funções são amplas de propósito, e às vezes amplas demais. Uma chave editor que só cria links também pode excluí-los, porque excluir faz parte da função editor. A correção são tokens por escopo, como links:write ou analytics:read, anexados diretamente a uma chave, em camadas sobre as funções.
Isso está no nosso roteiro e ainda não foi lançado. Hoje, as permissões de uma chave são seu espaço de trabalho mais sua função, e nada mais granular. Se você precisa de controle mais restrito agora, as duas alavancas são uma função mais baixa e uma expiração curta, além de chaves separadas por trabalho para que o raio de impacto de cada uma seja pequeno. O guia de início rápido da API e a referência de API e SDK mostram o modelo atual de chaves em código funcional, e equipes que também querem controle no nível de identidade podem ler sobre SCIM e SSO para ferramentas de marketing.
Leia o conteúdo principal: a lista de verificação de segurança para encurtador de URL cobre os controles ao redor da chave, da varredura de URLs às listas de permissões de IP.
Relacionados no blog
- API de encurtador de URL: um guia de início rápido de 30 minutos em cinco linguagens
- Encurtador de URL no n8n: nó HTTP Request ou nó da comunidade Elido
- Automação de links curtos: Make vs IFTTT vs n8n vs Zapier
- Webhooks para eventos de link
- Encurtador de URL com GitHub Actions: links curtos a partir do seu CI
Perguntas frequentes
O que são permissões de chave de API?
São o conjunto de ações que uma chave pode executar contra uma API: quais recursos ela pode ler, quais pode alterar e em qual conta. No Elido, as permissões de uma chave vêm do espaço de trabalho em que ela foi emitida e da função escolhida quando ela foi criada, então a mesma chave não pode atuar em outro espaço de trabalho nem acima dessa função.
O que é privilégio mínimo para chaves de API?
Significa que cada chave recebe o menor conjunto de permissões de que seu trabalho precisa, e nada além disso. Um painel que apenas lê contagens de cliques recebe uma chave viewer, um fluxo de trabalho que cria links recebe uma chave editor, e chaves admin ficam reservadas para a tarefa rara que gerencia webhooks, domínios ou membros. Assim, uma chave vazada só pode fazer o que aquele trabalho fazia.
Qual é a diferença entre escopos e funções de chave de API?
Um escopo é uma permissão restrita, como links:write, anexada diretamente a um token, enquanto uma função é um pacote nomeado de permissões, como editor. Funções são mais fáceis de entender; escopos são mais granulares. As chaves do Elido usam funções de espaço de trabalho hoje, e tokens por escopo estão planejados sobre elas, mas ainda não estão ativos.
Com que frequência as chaves de API devem ser rotacionadas?
A orientação comum é a cada 30 a 90 dias, além de imediatamente sempre que alguém que viu a chave sai, a chave aparece em um log ou o tráfego dela parece errado. Definir uma data de expiração na criação transforma esse cronograma em uma parada rígida, em vez de um lembrete de calendário que as pessoas ignoram.
Uma chave de API pode acessar endpoints administrativos?
No Elido, não. A API administrativa da plataforma só aceita uma sessão interativa com login e responde a uma chave de API com 403, seja qual for a função da pessoa que a criou. Configurações de espaço de trabalho que precisam de direitos de admin ainda são acessíveis, mas apenas por uma chave criada com a função admin ou owner.
Como as chaves de API devem ser armazenadas no lado do provedor?
Nunca em texto claro. O provedor deve armazenar um hash com chave do token e mostrar a você apenas um prefixo curto depois disso, para que uma cópia isolada do banco de dados não possa ser usada para chamar a API. O Elido gera hash de cada token com HMAC-SHA256 e um pepper no lado 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.
Grátis, sem necessidade de registo · 2 por dia