Ruoli e permessi delle chiavi API

Ogni chiave API di Elido ha un ruolo associato. Il ruolo determina cosa può fare la chiave. Scegliere il ruolo meno potente per ogni caso d'uso limita il raggio d'azione dei danni se una chiave dovesse mai essere trapelata.

I tre ruoli#

Ruolo	Cosa può fare
viewer	Leggere link, analytics e impostazioni del workspace. Non può creare, aggiornare o eliminare nulla.
editor	Tutto ciò che può fare il viewer, oltre a creare/aggiornare/eliminare link, gestire webhook ed eseguire importazioni massive.
admin	Tutto ciò che può fare l'editor, oltre a gestire i membri del workspace, la fatturazione, le chiavi API e le regole IP.

Imposti il ruolo quando crei una chiave in Settings → API keys. Non puoi cambiare il ruolo di una chiave dopo la creazione: emetti una nuova chiave con il ruolo corretto e revoca quella vecchia.

Quale ruolo usare#

Dashboard di analytics e integrazioni in sola lettura — usa viewer. Uno strumento di BI di terze parti, una pagina di stato che recupera il conteggio dei clic o uno script di reportistica interno hanno solo bisogno di leggere i dati.

Pipeline CI/CD che accorciano link — usa editor. Il tuo script di deploy che crea link per le campagne, la tua integrazione CMS che genera URL brevi e la maggior parte delle automazioni Zapier/Make rientrano in questa categoria.

Automazione admin — usa admin solo quando l'integrazione ha realmente bisogno di gestire i membri o la fatturazione. Questo è insolito. La maggior parte delle integrazioni che "sembrano admin" sono in realtà solo editor.

Server MCP / agente AI — editor è l'impostazione predefinita corretta a meno che l'agente non debba invitare membri. Il pacchetto @elido/mcp-server rispetta il ruolo della chiave.

Mappatura ruolo-endpoint#

Un riferimento rapido per le chiamate API comuni:

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

Il riferimento completo è su /api.

Errori di corrispondenza dello scope#

Quando una chiave non ha i permessi per un endpoint, l'API restituisce:

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

Il campo required_role ti dice esattamente di cosa hai bisogno. La soluzione è emettere una nuova chiave con il ruolo superiore (se intenzionale) o riconsiderare se l'integrazione debba effettivamente eseguire quella operazione.

Errori comuni:

• Usare una chiave viewer per creare link. Soluzione: emettere una chiave editor.
• Usare una chiave editor per invitare un membro del team da uno script. Soluzione: emettere una chiave admin, o usare invece la dashboard.
• Confondere il ruolo di appartenenza a livello di workspace (Owner/Member) con il ruolo della chiave API. Questi sono concetti separati. Un membro del team con accesso "Member" può comunque creare una chiave API con ruolo admin per le proprie integrazioni; i suoi permessi della dashboard non vengono ereditati dalla chiave.

Risoluzione dei problemi#

403 su un endpoint che dovrebbe essere consentito. Ricontrolla il ruolo della chiave in Settings → API keys: è mostrato nella colonna Role. Se il ruolo sembra corretto, conferma di inviare l'header Authorization: Bearer <token>, non un header di autenticazione Basic o un parametro di query.

401 Unauthorized. La chiave è stata revocata o il token è errato. Controlla la colonna Status per un badge revoked. Se la chiave è attiva, verifica di aver copiato l'intero token al momento della creazione.

La chiave funziona per le letture ma fallisce nelle scritture. La tua chiave è probabilmente un viewer. Emetti una nuova chiave editor.

Ho bisogno di permessi diversi per ogni integrazione. Emetti una chiave per ogni integrazione. Le chiavi sono gratuite da creare e facili da revocare individualmente, quindi non c'è motivo di condividere una chiave tra due sistemi.