Kimlik doğrulama

Herkese açık veriler kimlik bilgisi gerektirmez. Bir kuruluş adına yapılan her işlem, o kuruluşa ait bir kimlik bilgisi gerektirir: bir API anahtarı ya da bir OAuth istemcisinden alınan bir belirteç. İkisini de kuruluşun sahipleri ve yöneticileri panelde oluşturur.

API anahtarları

Bir API anahtarı brl_api_<id>_<secret> biçimindedir. Bearer belirteci olarak gönderin:

GET /v1/org/deals HTTP/1.1
Host: api.birlesa.com
Authorization: Bearer brl_api_01a1...

• Geçerlilik süresi: 1 ile 366 gün arası (varsayılan 90). Yenilemeyi planlayın: yeni anahtarı oluşturun, devreye alın, eskisini iptal edin.
• Bir kez gösterilir: yalnızca pepper eklenmiş bir özeti (hash) saklanır.
• İptal, her yerde bir dakika içinde; işlemler ve kuruluş kayıtlarının okunması için ise hemen geçerli olur.
• Ayrılan kişiler: biri kuruluştan ayrıldığında ya da yönetici olmaktan çıktığında, oluşturduğu anahtarlar ve OAuth istemcileri iptal edilir, kurduğu webhook'lar kapatılır.

İzinler

Bir anahtar herkese açık verileri okur. Bunun dışında neler yapabileceği, oluşturulurken belirlenir:

Her entegrasyona yalnızca kullandığı izni verin. İzni olmayan bir anahtar 403 ve no_org_read kodunu (ya da işleme karşılık gelen kodu) alır.

OAuth 2.0 istemci kimlik bilgileri

Uzun ömürlü bir anahtar tutmaması gereken makine entegrasyonları için panelde bir OAuth istemcisi oluşturun. Bir client_id (bir UUID) ve bir client_secret (brl_ocs_..., bir kez gösterilir) alırsınız. Bunları bir erişim belirteciyle değiştirin (RFC 6749 §4.4(yeni sekmede açılır)):

POST /oauth/token HTTP/1.1
Host: api.birlesa.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=client_credentials&scope=org:read

{"access_token": "brl_api_01a1...", "token_type": "Bearer", "expires_in": 3600, "scope": "org:read"}

• Belirteç, bir saat geçerli olan bir API anahtarıdır. Onu tam olarak bir anahtar gibi kullanın.
• scope istemcinin izinlerini daraltır; hepsini almak için göndermeyin. İstemcinin sahip olduğundan fazlasını istemek invalid_scope hatasıyla sonuçlanır.
• İstemci, client_id ve client_secret değerlerini HTTP Basic yerine form gövdesinde de gönderebilir.
• Bir istemcinin en çok 20 belirteci aynı anda geçerli olabilir; bunun ötesinde alınan yeni bir belirteç en eskisini iptal eder. Bir belirteci expires_in süresi dolmadan kısa bir süre öncesine kadar önbellekte tutun; her çağrı için yeni belirteç istemeyin.
• Bir istemciyi iptal etmek, belirteçlerini de iptal eder.
• Hatalar RFC 6749'a uyar: invalid_client (401), invalid_scope, unsupported_grant_type, invalid_request (400), slow_down (429). Yanıtlar hiçbir zaman önbelleğe alınmaz (Cache-Control: no-store).

Anahtarlar değil, kişiler

Üye paneli ve personel konsolu, kişilerin oturumunu Birlesa'nın kimlik sağlayıcısı üzerinden açar. Bu kişilerin belirteçleri API kimlik bilgisi değildir; API anahtarları da paneli açmaz. Görüşme mesajları ve uyuşmazlık kanıtları yalnızca paneldeki kişiler içindir.