API anahtarları

Bu rehberde: Kendi yazılımınızın, Zapier'in veya CRM'inizin OrqLabs'a bağlanması için bir API anahtarı oluşturursunuz. Kapsamları, yenilemeyi ve güvenli saklamayı öğrenirsiniz.

⏱ 10 dakika

API anahtarı nedir?#

API anahtarı, bir programın OrqLabs'a "benim" diyerek bağlanmasını sağlayan gizli bir şifredir. İnsanlar panele e-posta ve parolayla girer; programlar API anahtarıyla bağlanır.

• Anahtar organizasyona aittir; oluşturan kişi ayrılsa da çalışır.
• Yalnızca kendi organizasyonunuzun verisine erişir; Yönetim Paneli'ne erişemez.

Dikkat: API anahtarı bir paroladır. Tarayıcı veya mobil uygulama koduna koymayın; yalnızca sunucuda kullanın.

Anahtar oluşturma#

Ayarlar → API anahtarları.

1. ① Yeni API anahtarı düğmesine basın. Bir pencere açılır.
2. Ad: kullanım yerini yazın ("CRM senkronu", "Zapier").
3. ② Kapsamlar: yalnızca gerekenleri seçin (aşağıda).
4. Oluştur. ③ Anahtar yalnızca bu ekranda bir kez gösterilir. Kopyalayın ve bir parola kasasına kaydedin. Kaybederseniz yenisini oluşturmanız gerekir.

Biçim: af_live_ + 40 rastgele karakter. Listede yalnızca ön ek ve son 4 karakter, oluşturan, oluşturma ve son kullanım zamanı görünür.

Kullanım#

curl -H "X-Api-Key: af_live_..." "https://api.orqlabs.com/api/v1/orgs/$ORG/leads?status=QUALIFIED"

• Başlık: X-Api-Key.
• Adresteki organizasyon kimliği anahtarın organizasyonu olmalıdır; aksi hâlde 403.
• Anahtarla yapılan işlemler denetim günlüğünde "API anahtarı" olarak görünür.
• Canlı API belgesi: https://api.orqlabs.com/api/docs (Authorize → X-Api-Key).

Kapsamlar#

Kapsam, anahtarın hangi işlere erişebileceğini sınırlar. Panelde seçilebilen liste esastır; aşağıdakiler örnektir.

Kapsam dışı istek 403 INSUFFICIENT_SCOPE döner. Kapsamlar sonradan değiştirilemez; yeni anahtar oluşturun.

Kimler oluşturabilir?#

• Sahip ve Yönetici oluşturur ve siler. Üye ve İzleyici listeyi (maskeli) görür.
• Plan: FREE en fazla 2, STARTER 5, PRO/ENTERPRISE sınırsız anahtar.

Yenileme ve iptal#

• İptal: listede İptal et. Anında geçersiz olur; kullanan sistemler 401 alır.
• Kesintisiz yenileme: yeni anahtar oluşturun → sistemleri güncelleyin → Son kullanım sütununda eski anahtarın trafiği sıfırlanınca eskiyi silin.
• Önerilen döngü: 90 günde bir; sızıntı şüphesinde hemen.

Beklenmedik kullanım artışı sızıntı belirtisi olabilir; Ayarlar → Kullanım ve denetim günlüğünü izleyin.

Hız sınırları#

Yanıt başlıkları: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Güvenlik pratikleri#

• Anahtarı ortam değişkeninde veya parola kasasında saklayın; git'e yazmayın. af_live_ deseni için gizli tarama kuralı ekleyin.
• En dar kapsamı verin; okuma ve yazma için ayrı anahtar.
• Her sistem için ayrı anahtar; sızıntıda yalnızca birini iptal edersiniz.
• İzin verilen IP'ler ile anahtarı belirli adreslere kısıtlayın.
• Webhook imzası ayrı bir mekanizmadır; API anahtarını webhook'lara koymayın.

Örnek: Node.js#

const API = "https://api.orqlabs.com/api/v1";
const ORG = process.env.ORQLABS_ORG_ID;
const headers = { "X-Api-Key": process.env.ORQLABS_API_KEY, "Content-Type": "application/json" };

export async function createLead(lead) {
  const res = await fetch(`${API}/orgs/${ORG}/leads`, { method: "POST", headers, body: JSON.stringify(lead) });
  if (res.status === 429) {
    const wait = Number(res.headers.get("Retry-After") ?? 5) * 1000;
    await new Promise((r) => setTimeout(r, wait));
    return createLead(lead);
  }
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  return res.json();
}

Hatalar#

Sık sorulan sorular#

Zapier için API anahtarı mı webhook mu kullanmalıyım? OrqLabs'ı Zapier'den başlatmak için webhook tetikleyicisi daha kolaydır. Zapier'in OrqLabs verisini okuması veya yazması için API anahtarı gerekir.

Anahtarı kaybettim. Tekrar gösterilemez. Yeni anahtar oluşturun ve eskisini iptal edin.

Sonraki adım#

• Genel API hızlı başlangıç
• Giden webhook'lar
• Güvenlik ve gizlilik