Roluri și permisiuni pentru cheile API

Fiecare cheie API Elido are un rol atașat. Rolul determină ce poate face cheia. Alegerea celui mai puțin puternic rol pentru fiecare caz de utilizare limitează raza de impact dacă o cheie este vreodată scursă.

Cele trei roluri

Rol	Ce poate face
viewer	Citește linkuri, analize și setările workspace-ului. Nu poate crea, actualiza sau șterge nimic.
editor	Tot ce poate face viewer, plus creare/actualizare/ștergere linkuri, gestionare webhook-uri și rulare importuri în bloc.
admin	Tot ce poate face editor, plus gestionarea membrilor workspace-ului, a facturării, a cheilor API și a regulilor IP.

Setezi rolul când creezi o cheie în Settings → API keys. Nu poți schimba rolul unei chei după creare — emite o cheie nouă cu rolul potrivit și revoc-o pe cea veche.

Ce rol să folosești

Dashboard-uri de analiză și integrări doar-citire — folosește viewer. Un instrument BI terț, o pagină de status care preia numărul de clickuri sau un script intern de raportare au nevoie doar să citească date.

Pipeline-uri CI/CD care scurtează linkuri — folosește editor. Scriptul tău de deploy care creează linkuri de campanie, integrarea CMS care generează URL-uri scurte și majoritatea automatizărilor Zapier/Make se încadrează aici.

Automatizare de administrare — folosește admin doar când integrarea are cu adevărat nevoie să gestioneze membri sau facturarea. Acest caz este neobișnuit. Majoritatea integrărilor care „par admin" sunt de fapt doar editor.

Server MCP / agent AI — editor este alegerea implicită corectă, cu excepția cazului în care agentul are nevoie să invite membri. Pachetul @elido/mcp-server respectă rolul cheii.

Maparea rol-endpoint

O referință rapidă pentru apelurile API comune:

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

Referința completă este la /api.

Erori de nepotrivire a scopului

Când o cheie nu are permisiunea pentru un endpoint, API-ul returnează:

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

Câmpul required_role îți spune exact de ce ai nevoie. Rezolvarea este să emiți o cheie nouă cu rolul superior (dacă asta este intenționat) sau să reconsideri dacă integrarea ar trebui să efectueze deloc acea operațiune.

Greșeli comune:

• Folosirea unei chei viewer pentru a crea linkuri. Soluție: emite o cheie editor.
• Folosirea unei chei editor pentru a invita un membru al echipei dintr-un script. Soluție: emite o cheie admin, sau folosește dashboard-ul în schimb.
• Confundarea rolului de membru la nivel de workspace (Owner/Member) cu rolul cheii API. Acestea sunt concepte separate. Un membru al echipei cu acces „Member" poate crea totuși o cheie API cu rol admin pentru propriile integrări — permisiunile sale din dashboard nu sunt moștenite de cheie.

Depanare

403 pe un endpoint care ar trebui permis. Verifică din nou rolul cheii în Settings → API keys — este afișat în coloana Role. Dacă rolul pare corect, confirmă că trimiți headerul Authorization: Bearer <token>, nu un header Basic auth sau un parametru de query.

401 Unauthorized. Cheia fie este revocată, fie token-ul este greșit. Verifică coloana Status pentru un badge revoked. Dacă cheia este activă, verifică dacă ai copiat token-ul complet la creare.

Cheia funcționează pentru citiri, dar eșuează la scrieri. Cheia ta este probabil viewer. Emite o cheie nouă editor.

Am nevoie de permisiuni diferite per integrare. Emite câte o cheie per integrare. Cheile sunt gratuite de creat și ușor de revocat individual, deci nu există niciun motiv să partajezi o cheie între două sisteme.