Funções e permissões de chaves de API

Cada chave de API da Elido possui uma função atribuída. A função determina o que a chave pode fazer. Escolher a função menos poderosa para cada caso de uso limita o impacto caso uma chave seja vazada.

As três funções#

Função	O que pode fazer
viewer	Ler links, análises e configurações do workspace. Não pode criar, atualizar ou excluir nada.
editor	Tudo o que o viewer pode fazer, além de criar/atualizar/excluir links, gerenciar webhooks e realizar importações em massa.
admin	Tudo o que o editor pode fazer, além de gerenciar membros do workspace, faturamento, chaves de API e regras de IP.

Você define a função ao criar uma chave em Settings → API keys. Não é possível alterar a função de uma chave após a criação — emita uma nova chave com a função correta e revogue a antiga.

Qual função usar#

Dashboards de análise e integrações somente leitura — use viewer. Uma ferramenta de BI de terceiros, uma página de status que extrai contagens de cliques ou um script de relatório interno só precisam ler dados.

Pipelines de CI/CD que encurtam links — use editor. Seu script de deploy que cria links de campanha, sua integração de CMS que gera URLs curtas e a maioria das automações do Zapier/Make se enquadram aqui.

Automação de administração — use admin apenas quando a integração realmente precisar gerenciar membros ou faturamento. Isso é incomum. A maioria das integrações que "parecem admin" são, na verdade, apenas editores.

Servidor MCP / Agente de IA — editor é o padrão correto, a menos que o agente precise convidar membros. O pacote @elido/mcp-server respeita a função da chave.

Mapeamento de função para endpoint#

Uma referência rápida para chamadas de API comuns:

GET    /v1/links              → viewer
POST   /v1/links              → editor
PUT    /v1/links/:id          → editor
DELETE /v1/links/:id          → editor
GET    /v1/analytics/clicks   → viewer
GET    /v1/workspace          → viewer
POST   /v1/workspace/members  → admin
POST   /v1/api-keys           → admin

A referência completa está em /api.

Erros de incompatibilidade de escopo#

Quando uma chave não tem permissão para um endpoint, a API retorna:

{
  "error": "forbidden",
  "message": "this key requires the admin role to manage workspace members",
  "required_role": "admin",
  "key_role": "editor"
}

O campo required_role informa exatamente o que você precisa. A correção é emitir uma nova chave com a função superior (se isso for intencional) ou reconsiderar se a integração deveria estar realizando essa operação.

Erros comuns:

• Usar uma chave viewer para criar links. Solução: emita uma chave editor.
• Usar uma chave editor para convidar um membro da equipe por meio de um script. Solução: emita uma chave admin ou use o dashboard.
• Confundir a função de membro no nível do workspace (Owner/Member) com a função da chave de API. Estes são conceitos separados. Um membro da equipe com acesso "Member" ainda pode criar uma chave de API com função admin para suas próprias integrações — suas permissões do dashboard não são herdadas pela chave.

Solução de problemas#

403 em um endpoint que deveria ser permitido. Verifique novamente a função da chave em Settings → API keys — ela é exibida na coluna Role. Se a função parecer correta, confirme se você está enviando o cabeçalho Authorization: Bearer <token>, e não um cabeçalho de autenticação Basic ou um parâmetro de consulta.

401 Unauthorized. A chave foi revogada ou o token está incorreto. Verifique a coluna Status para ver se há um selo revoked. Se a chave estiver ativa, verifique se você copiou o token completo no momento da criação.

A chave funciona para leituras, mas falha em gravações. Sua chave provavelmente é um viewer. Emita uma nova chave editor.

Preciso de permissões diferentes por integração. Emita uma chave por integração. As chaves são gratuitas para criar e fáceis de revogar individualmente, portanto, não há motivo para compartilhar uma chave entre dois sistemas.