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.
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.
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
- Account menüsünü (avatarınız) açın ve API keys'i seçin.
- Create key'i seçin, daha sonra tanıyacağınız bir ad verin ve isterseniz bir son kullanma tarihi belirleyin.
- Token'ı kopyalayın. Yalnızca bir kez gösterilir; Veyra yalnızca bir özetini (hash) saklar.
Ya da elinizdeki bir anahtarla API'den:
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
- Agent'ı ve onun API keys sekmesini açın.
- Create key'i seçin ve kullanılacağı yere göre adlandırın.
- Token'ı kopyalayın; yalnızca bir kez gösterilir.
Ya da Create an agent API key uç noktasını çağırın:
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 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:
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. |