API anahtarı rolleri ve izinleri

Her Elido API anahtarına bir rol atanmıştır. Rol, anahtarın ne yapabileceğini belirler. Her kullanım senaryosu için en az yetkili rolü seçmek, bir anahtar sızdırıldığında etki alanını sınırlar.

Üç rol

Rol	Ne yapabilir
viewer	Bağlantıları, analitikleri ve çalışma alanı ayarlarını okur. Hiçbir şey oluşturamaz, güncelleyemez veya silemez.
editor	Viewer'ın yapabildiği her şey, artı bağlantı oluşturma/güncelleme/silme, webhook yönetimi ve toplu içe aktarma (bulk import) çalıştırma.
admin	Editor'ın yapabildiği her şey, artı çalışma alanı üyelerini, faturalandırmayı, API anahtarlarını ve IP kurallarını yönetme.

Rolü, Ayarlar → API anahtarları'nda bir anahtar oluştururken ayarlarsınız. Bir anahtarın rolünü oluşturduktan sonra değiştiremezsiniz — doğru rolle yeni bir anahtar oluşturun ve eskisini iptal edin.

Hangi rolü kullanmalı

Analitik panoları ve salt-okunur entegrasyonlar — viewer kullanın. Üçüncü taraf bir BI aracı, tıklama sayılarını çeken bir durum sayfası veya dahili bir raporlama betiği yalnızca veri okumaya ihtiyaç duyar.

Bağlantı kısaltan CI/CD hatları — editor kullanın. Kampanya bağlantıları oluşturan dağıtım betiğiniz, kısa URL üreten CMS entegrasyonunuz ve çoğu Zapier/Make otomasyonu buraya girer.

Admin otomasyonu — yalnızca entegrasyon gerçekten üyeleri veya faturalandırmayı yönetmeye ihtiyaç duyduğunda admin kullanın. Bu nadirdir. "Admin gibi hissettiren" çoğu entegrasyon aslında yalnızca editor'dür.

MCP sunucusu / AI ajanı — ajan üye davet etmesi gerekmedikçe editor doğru varsayılandır. @elido/mcp-server paketi anahtarın rolüne uyar.

Rol-uç nokta eşlemesi

Yaygın API çağrıları için hızlı bir referans:

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

Tam referans /api adresindedir.

Kapsam uyuşmazlığı hataları

Bir anahtarın bir uç nokta için izni olmadığında, API şunu döndürür:

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

required_role alanı size tam olarak neye ihtiyacınız olduğunu söyler. Çözüm, (kasıtlıysa) daha yüksek rolle yeni bir anahtar oluşturmak veya entegrasyonun bu işlemi gerçekten yapması gerekip gerekmediğini yeniden düşünmektir.

Yaygın hatalar:

• Bağlantı oluşturmak için bir viewer anahtarı kullanmak. Çözüm: bir editor anahtarı oluşturun.
• Bir betikten ekip üyesi davet etmek için bir editor anahtarı kullanmak. Çözüm: bir admin anahtarı oluşturun veya bunun yerine panoyu kullanın.
• Çalışma alanı düzeyindeki üyelik rolünü (Owner/Member) API anahtarı rolüyle karıştırmak. Bunlar ayrı kavramlardır. "Member" erişimine sahip bir ekip üyesi, kendi entegrasyonları için yine de admin rollü bir API anahtarı oluşturabilir — pano izinleri anahtara kalıtılmaz.

Sorun giderme

İzin verilmesi gereken bir uç noktada 403 alıyorum. Ayarlar → API anahtarları'nda anahtarın rolünü kontrol edin — Rol sütununda gösterilir. Rol doğru görünüyorsa, bir Basic auth başlığı veya bir sorgu parametresi değil, Authorization: Bearer <token> başlığı gönderdiğinizi doğrulayın.

401 Unauthorized. Anahtar ya iptal edilmiş ya da jeton yanlıştır. Durum sütununda bir revoked rozeti olup olmadığını kontrol edin. Anahtar aktifse, oluşturma anında tam jetonu kopyaladığınızı doğrulayın.

Anahtar okumalarda çalışıyor ama yazmalarda başarısız oluyor. Anahtarınız muhtemelen bir viewer. Yeni bir editor anahtarı oluşturun.

Entegrasyon başına farklı izinlere ihtiyacım var. Entegrasyon başına bir anahtar oluşturun. Anahtarların oluşturulması ücretsiz ve tek tek iptal edilmesi kolaydır, bu yüzden iki sistem arasında bir anahtarı paylaşmak için bir neden yoktur.