Roles y permisos de las claves de API

Cada clave de API de Elido tiene un rol asignado. El rol determina lo que la clave puede hacer. Elegir el rol con menos privilegios para cada caso de uso limita el radio de impacto si una clave se llega a filtrar.

Los tres roles#

Rol	Qué puede hacer
viewer	Leer enlaces, analíticas y ajustes del espacio de trabajo. No puede crear, actualizar ni eliminar nada.
editor	Todo lo que puede hacer el viewer, además de crear/actualizar/eliminar enlaces, gestionar webhooks y ejecutar importaciones masivas.
admin	Todo lo que puede hacer el editor, además de gestionar miembros del espacio de trabajo, facturación, claves de API y reglas de IP.

Usted establece el rol cuando crea una clave en Settings → API keys. No puede cambiar el rol de una clave después de su creación; emita una nueva clave con el rol correcto y revoque la antigua.

Qué rol utilizar#

Tableros de analíticas e integraciones de solo lectura — use viewer. Una herramienta de BI de terceros, una página de estado que extrae recuentos de clics o un script de informes internos solo necesitan leer datos.

Pipelines de CI/CD que acortan enlaces — use editor. Su script de despliegue que crea enlaces de campaña, su integración de CMS que genera URLs cortas y la mayoría de las automatizaciones de Zapier/Make entran en esta categoría.

Automatización de administración — use admin solo cuando la integración realmente necesite gestionar miembros o facturación. Esto es poco común. La mayoría de las integraciones que "parecen de administración" son en realidad solo de editores.

Servidor MCP / agente de IA — editor es el valor predeterminado correcto a menos que el agente necesite invitar a miembros. El paquete @elido/mcp-server respeta el rol de la clave.

Mapeo de rol a endpoint#

Una referencia rápida para llamadas comunes a la API:

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

La referencia completa se encuentra en /api.

Errores de desajuste de alcance#

Cuando una clave no tiene permiso para un endpoint, la API devuelve:

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

El campo required_role le indica exactamente lo que necesita. La solución es emitir una nueva clave con el rol superior (si es intencionado) o reconsiderar si la integración debería estar realizando esa operación en absoluto.

Errores comunes:

• Usar una clave viewer para crear enlaces. Solución: emita una clave editor.
• Usar una clave editor para invitar a un miembro del equipo desde un script. Solución: emita una clave admin o use el tablero en su lugar.
• Confundir el rol de membresía a nivel de espacio de trabajo (Owner/Member) con el rol de la clave de API. Estos son conceptos separados. Un miembro del equipo con acceso "Member" todavía puede crear una clave de API con rol admin para sus propias integraciones; sus permisos del tablero no son heredados por la clave.

Resolución de problemas#

403 en un endpoint que debería estar permitido. Verifique de nuevo el rol de la clave en Settings → API keys — se muestra en la columna Role. Si el rol parece correcto, confirme que está enviando la cabecera Authorization: Bearer <token>, no una cabecera de Basic auth o un parámetro de consulta.

401 Unauthorized. La clave ha sido revocada o el token es incorrecto. Verifique la columna Status para ver si tiene una etiqueta de revoked. Si la clave está activa, verifique que copió el token completo en el momento de la creación.

La clave funciona para lecturas pero falla en escrituras. Su clave es probablemente una viewer. Emita una nueva clave editor.

Necesito diferentes permisos por integración. Emita una clave por integración. Las claves son gratuitas de crear y fáciles de revocar individualmente, por lo que no hay razón para compartir una clave entre dos sistemas.