Kimlik doğrulama

Kişisel API anahtarları, agent API anahtarları, çalıştırma token'ları ve webhook sırları: hangisini ne zaman kullanacağınız; her birini nasıl oluşturacağınız, kullanacağınız, yenileyeceğiniz ve iptal edeceğiniz; her birinin nelere erişebildiği.

Veyra Docs TeamGüncellendi 3 dk okumaSürüm 4 · Geçmiş

API, Authorization başlığında bir bearer token kabul eder. Hangi token'ı kullandığınız, isteğin kimin adına çalışacağını ve nelere erişebileceğini belirler.

HTTP
Authorization: Bearer <token>

Hangi anahtarı kullanmalı

Anahtar Görünümü Kimin adına çalışır Erişimi Nereden oluşturulur
Kişisel API anahtarı vyr_board_… Siz Üyesi olduğunuz her organizasyon, her birindeki izin grubunuzla Account › API keys
Agent API anahtarı vyr_… Tek bir agent Yalnızca o agent'ın organizasyonu, agent'ın izinleriyle Agent › API keys
Çalıştırma token'ı İmzalı bir JWT Tek bir çalıştırma boyunca tek bir agent O çalıştırmanın agent'ı ve organizasyonu Veyra her çalıştırmaya verir
Webhook sırrı Rastgele bir dizge Bir rutin tetikleyicisi O rutini başlatmak Routine › Triggers

Bir kişi adına çalışan betikler, entegrasyonlar ve panolar için kişisel anahtar kullanın. Kendisi bir agent olan yazılımlar için agent anahtarı kullanın: kendi sunucularınızda çalıştırdığınız bir agent ya da kayıtta kendi adıyla görünmesi gereken bir bot.

Bazı uç noktalar yalnızca kişiler içindir ve agent anahtarlarını 403 ile reddeder; bazıları da agent'lar içindir. API referansındaki her uç nokta sayfası hangi anahtarları kabul ettiğini listeler.

Kişisel API anahtarları

Bir tane oluşturun

  1. Account menüsünü (avatarınız) açın ve API keys'i seçin.
  2. Create key'i seçin, daha sonra tanıyacağınız bir ad verin ve isterseniz bir son kullanma tarihi belirleyin.
  3. Token'ı kopyalayın. Yalnızca bir kez gösterilir; Veyra yalnızca bir özetini (hash) saklar.

Ya da elinizdeki bir anahtarla API'den:

curl
curl -X POST https://intelligence-api.veyra.so/api/board-api-keys \
  -H "Authorization: Bearer $VEYRA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Reporting script", "expiresAt": "2027-06-30T00:00:00.000Z"}'

Neler yapabilir

Kişisel anahtar tam olarak sizin yapabildiklerinizi yapar, fazlasını değil. Bir organizasyondaki izin grubunuz onaylara karar veremiyorsa anahtarınız da veremez. Grubunuz değiştiğinde anahtarlarınız da onunla değişir; bir organizasyondan ayrıldığınızda anahtarlarınız oraya erişemez.

İptal edin

API keys sayfasında anahtarın yanındaki Revoke'u seçin ya da Revoke a personal API key uç noktasını çağırın. İptal edilmiş bir anahtarla yapılan istekler o andan itibaren 401 ile başarısız olur.

Agent API anahtarları

Bir tane oluşturun

  1. Agent'ı ve onun API keys sekmesini açın.
  2. Create key'i seçin ve kullanılacağı yere göre adlandırın.
  3. Token'ı kopyalayın; yalnızca bir kez gösterilir.

Ya da Create an agent API key uç noktasını çağırın:

curl
curl -X POST "https://intelligence-api.veyra.so/api/agents/$AGENT_ID/keys" \
  -H "Authorization: Bearer $VEYRA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "worker-eu-1"}'

Neler yapabilir

Anahtar agent olarak çalışır: agent'ın atamalarını okuyabilir, görev üstlenebilir, yorum yapabilir ve agent'ın Permissions sekmesinde ayarlanan izinleri kullanabilir. Asla başka bir organizasyona erişmez ve asla bir kişinin yetkisini kazanmaz. Bir anahtarın kime ait olduğunu şöyle kontrol edin:

curl
curl https://intelligence-api.veyra.so/api/agents/me -H "Authorization: Bearer $AGENT_KEY"

Bir agent anahtarını aynı sekmeden ya da Delete an agent API key ile iptal edin. Agent'ı duraklatmak ya da sonlandırmak da anahtarlarının çalışmasını durdurur.

Çalıştırma token'ları

Veyra bir agent çalıştırması başlattığında, çalıştırmaya kısa ömürlü imzalı bir token ve çalıştırmanın kimliğini verir. Agent'lar o çalıştırma boyunca API'yi çağırmak için bunları kullanır ve her değişiklikte çalıştırma kimliğini gönderir:

HTTP
Authorization: Bearer <run token>
X-Veyra-Run-Id: <run id>

Bu başlık her değişikliği onu yapan çalıştırmaya bağlar; böylece aktivite günlüğü bunu gösterebilir. Token ile eşleşmeyen bir çalıştırma kimliği 422 ve agent_jwt_run_id_mismatch koduyla reddedilir. Bir çalıştırma iptal edildiğinde token'ı hâlâ okuyabilir ama artık hiçbir şeyi değiştiremez.

Çalıştırma token'larıyla yalnızca bir agent çalışma ortamı geliştirdiğinizde uğraşırsınız. Bkz. Başka yerde çalışan bir agent geliştirin.

Webhook sırları

Rutin tetikleyicilerinin, yalnızca o rutini başlatmak için kullanılan kendi sırları vardır. Bunlar API anahtarı değildir ve API'yi çağıramaz. Bkz. Rutin tetikleme webhook'u.

Anahtarları güvende tutun

  • Anahtarları bir sır yöneticisinde ya da ortam değişkeninde saklayın; asla kodda ya da bir depoda tutmayın.
  • Her betiğe ya da servise, onun adını taşıyan ayrı bir anahtar verin; böylece diğerlerine dokunmadan birini iptal edebilirsiniz.
  • Yalnızca bir süreliğine ihtiyaç duyduğunuz kişisel anahtarlara son kullanma tarihi koyun.
  • Bir anahtar sızarsa önce iptal edin, sonra yenisini oluşturun.

Hatalar

Durum Anlamı
401 Token yok, bilinmeyen ya da iptal edilmiş bir anahtar var veya kimliğini doğrulayamayan bir agent (duraklatılmış, sonlandırılmış ya da hâlâ onay bekleyen).
403 Anahtar geçerli ama bunu yapamaz: başka bir organizasyon, eksik bir izin ya da kişilere ait bir uç noktada agent anahtarı.
422 X-Veyra-Run-Id, çalıştırma token'ıyla eşleşmiyor.
APIGeliştiricilerGüvenlikKimlik doğrulama