İçeriğe geçin

Kimlik doğrulama

Kimlik doğrulama

Authorization başlığındaki gizli bir anahtar, kendi kayıtlarınıza ulaşmanın yoludur. Başka bir giriş yolu yoktur ve hiçbir istek oturum çerezi ile doğrulanmaz. Kategori uç noktaları bunun istisnasıdır: kimsenin verisini değil, istediğimiz alanları anlatırlar ve anahtar olmadan yanıt verirler.

Anahtarlar

Bir anahtar yalnızca oluşturulduğu anda bir kez gösterilir. Onu sunucuların okuyabileceği, tarayıcının okuyamayacağı bir yerde saklayın.

  • pc_sk_live_…
  • pc_sk_test_…

Test ile canlı ayrı kalır

Kip, parametre olarak geçilmek yerine kimlik bilgisinin kendisine işlenmiştir; bu yüzden bir test anahtarı gerçek pasaportlarınızı ne okuyabilir ne de değiştirebilir. Yanlış yönlendirilmiş bir istek, yanlış kataloğa ulaşmak yerine başarısız olur. Test pasaportları, pasaportun kendisinde yapılan son değişiklikten 90 gün sonra silinir.

Anahtarı gönderme

HTTPS üzerinden Bearer kimlik doğrulaması. Başka bir yöntem kabul edilmez ve başlığı taşımayan bir istek, kayıtlarınızdan herhangi birine ulaşmadan reddedilir.

İstek
curl "https://passportcraft.com/api/v1/whoami" \
  -H "Authorization: Bearer pc_sk_live_…"

Tarayıcıdaki kimlik bilgileri bilinçli olarak desteklenmez. Anahtarın yeri sunucudur; ön uç kodundaki bir anahtar, yayımlanmış bir anahtardır.

Kapsamlar

Bir anahtar, oluşturulurken seçilen sabit bir kapsam kümesi taşır. Uç noktasının istediği kapsamı taşımayan bir istek reddedilir ve ret yanıtı eksik olan izni adıyla belirtir.

Kapsam gerekmez

Geçerli bir kimlik bilgisi yeterlidir. Bu uç noktalar tek bir kuruluşa ait hiçbir şey döndürmez.

Kimlik bilgisi gerekmez

Anahtar olmadan okunabilir. Bu uç noktalar ürünün kendisini anlatır — hangi kategoriler var ve her biri hangi alanları ister — bu yüzden yanıt her okuyucu için aynıdır. Anahtar göndermek yine kabul edilir; iptal edilmiş veya süresi dolmuş bir anahtar ise yine reddedilir. Anahtar olmadan, istemci adresi başına dakikada 60 istek olan anonim sayaca tabi olursunuz.

Birden çok kuruluş için tek anahtar

Bir anahtar tek bir kuruluşa aittir ve yalnızca yetkisinin bulunduğu başka bir kuruluş için işlem yapabilir. Müşterileri yöneten bir kuruluş, anahtarlarına her müşteri için ayrı ayrı seçilen izinlerle erişim verebilir. Her istek, yolunda tek bir kuruluşu adlandırır ve yalnızca o kuruluş üzerinde işlem yapar.

Bir anahtara müşteri erişimi verme

Yolda müşterinin kimliğini, gövdede ise anahtarın key_id değerini ve verilecek kapsamları belirterek POST /organizations/{organization}/grants çağrısını yapın. Çağrıyı yapan anahtarın kendi kuruluşunda keys:admin kapsamına sahip olması gerekir. Bir müşteriye yalnızca anahtarın kendi kuruluşunda zaten sahip olduğu kapsamlar verilebilir; filings:write için ayrıca müşterinin yazılı yetkisinin önce onaylanmış olması gerekir.

İstek
curl "https://passportcraft.com/api/v1/organizations/{client}/grants" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key_id": "K3n9Qw2P", "scopes": ["passports:read", "passports:write"]}'

Erişim sona erdiğinde

DELETE /organizations/{organization}/grants/{keyId} tek bir yetkiyi sona erdirir; anahtar, yetkisinin bulunduğu her diğer kuruluşta çalışmaya devam eder. Bir müşteri, bir anahtarın erişimini kendi Ayarlar bölümünden de kaldırabilir. Bir müşteri ile kuruluşunuz arasındaki iş birliğinin sona ermesi, o müşteri üzerindeki tüm yetkileri bir kerede sona erdirir. Bundan sonra, müşteri için yapılan her istek 404 organization_not_found_or_not_granted yanıtını alır; bu, var olmayan bir kuruluş için verilen yanıtla aynıdır. İkisini birbirinden ayırt etmek için GET /organizations çağrısını yapın: erişimini kaybettiğiniz bir kuruluş artık listede yer almaz.

GET /organizations içindeki her kayıt, kuruluşun adını taşıyan display_name alanını ve link_status alanını içerir. link_status değeri, kuruluşunuzun yönettiği bir müşteri için "accepted", kendi kuruluşunuz için ise null olur.

Müşterileri yöneten bir kuruluş için canlı anahtarlar

Müşterileri yöneten bir kuruluş, kendi planı veya müşterilerinden en az birinin planı ücretli bir Pro ya da Scale planıysa canlı anahtar oluşturabilir. Deneme aşamasındaki veya ödemesi gecikmiş bir plan sayılmaz. Her istek yine de yolda adlandırılan kuruluşun planına göre denetlenir.

Örnek: bir zamanlayıcı, on müşteri

Her gece çalışan bir iş, anahtarının işlem yapabileceği kuruluşları listelemek için GET /organizations çağrısını yapar, ardından her müşteriyi ayrı ayrı senkronize eder. Ayrılan bir müşteri listeden düşer; böylece iş, her gece bir 404 kaydetmek yerine o müşteriyi çağırmayı bırakır.

İstek
const base = 'https://passportcraft.com/api/v1'
const headers = { 'Authorization': 'Bearer ' + process.env.PASSPORTCRAFT_API_KEY }

const { data } = await (await fetch(base + '/organizations', { headers })).json()
const clients = data.filter((connection) => connection.link_status === 'accepted')

for (const client of clients) {
  // One organization per request, always named in the path.
  await syncCatalogue(client.organization_id, client.display_name)
}