API key roles and permissions

Every Elido API key has a role attached. The role determines what the key can do. Picking the least-powerful role for each use case limits the blast radius if a key is ever leaked.

The three roles#

Role	What it can do
viewer	Read links, analytics, and workspace settings. Cannot create, update, or delete anything.
editor	Everything viewer can do, plus create/update/delete links, manage webhooks, and run bulk imports.
admin	Everything editor can do, plus manage workspace members, billing, API keys, and IP rules.

You set the role when you create a key in Settings → API keys. You cannot change a key's role after creation — issue a new key with the right role and revoke the old one.

Which role to use#

Analytics dashboards and read-only integrations — use viewer. A third-party BI tool, a status page pulling click counts, or an internal reporting script only needs to read data.

CI/CD pipelines that shorten links — use editor. Your deploy script creating campaign links, your CMS integration generating short URLs, and most Zapier/Make automations fall here.

Admin automation — use admin only when the integration genuinely needs to manage members or billing. This is unusual. Most integrations that "feel admin" are actually just editors.

MCP server / AI agent — editor is the right default unless the agent needs to invite members. The @elido/mcp-server package respects the key's role.

Role-to-endpoint mapping#

A quick reference for common API calls:

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

The full reference is at /api.

Scope mismatch errors#

When a key doesn't have permission for an endpoint, the API returns:

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

The required_role field tells you exactly what you need. The fix is to issue a new key with the higher role (if that's intentional) or to reconsider whether the integration should be doing that operation at all.

Common mistakes:

Using a viewer key to create links. Solution: issue an editor key.
Using an editor key to invite a team member from a script. Solution: issue an admin key, or use the dashboard instead.
Confusing workspace-level membership role (Owner/Member) with API key role. These are separate concepts. A team member with "Member" access can still create an admin-role API key for their own integrations — their dashboard permissions are not inherited by the key.

Troubleshooting#

403 on an endpoint that should be allowed. Double-check the key role in Settings → API keys — it's shown in the Role column. If the role looks right, confirm you're sending the Authorization: Bearer <token> header, not a Basic auth header or a query parameter.

401 Unauthorized. The key is either revoked or the token is wrong. Check the Status column for a revoked badge. If the key is active, verify you copied the full token at creation time.

Key works for reads but fails on writes. Your key is probably a viewer. Issue a new editor key.

I need different permissions per integration. Issue one key per integration. Keys are free to create and easy to revoke individually, so there's no reason to share a key between two systems.