İçeriğe geç
Apex Settlement

Kimlik doğrulama

API anahtarları, taşıyabilecekleri izinler, güvenli kullanım ve 401 ile 403 yanıtları.

API anahtarınızı gönderin

Her istek, bir API anahtarını bearer token olarak taşır:

curl
curl "$APEX_BASE_URL/v1/balances" \
  -H "Authorization: Bearer $APEX_API_KEY"

Bir anahtar ak_test_ (sandbox) ya da ak_live_ (production) ile başlar; ardından 8 karakterlik bir ön ek, bir alt çizgi ve 52 karakterlik bir gizli bölüm gelir. Tam olarak bir Authorization başlığı gönderin: ikinci bir başlıkla birlikte gönderilen anahtar reddedilir.

Anahtarları sunucularınızda tutun

Bir API anahtarı, izinleri dahilinde tüm hesabınız adına işlem yapar. Onu yalnızca arka ucunuzda kullanın; hiçbir zaman tarayıcıya, mobil uygulamaya ya da bir kod deposuna koymayın. Gizli değer deponuzda saklayın ve loglara yazdırmayın.

Anahtar oluşturun

API anahtarları API üzerinden değil, müşteri panelinden oluşturulur. Yönetici rolüne sahip bir kişi API anahtarları sayfasını açar, Anahtar oluştur'u seçer ve şunları belirler:

AlanNe işe yarar
AdAnahtarı neyin kullanacağı, örneğin "ERP senkronu".
İzinlerAnahtarın neler yapabileceği. En az bir tane; aşağıya bakın.
İzinli adreslerİsteğe bağlı. Anahtarın kullanılabileceği IP adresleri ya da CIDR aralıkları. Boş bırakılırsa her adres kabul edilir.
Bitiş tarihiİsteğe bağlı. Anahtar o günün sonunda (UTC) çalışmayı bırakır.

Anahtar yalnızca oluşturulduğu anda bir kez gösterilir. Kaybolursa iptal edip yenisini oluşturun. Bir hesapta iptal edilmemiş en fazla 25 anahtar bulunabilir.

Panel her anahtarı durumuyla (active Etkin, expired Süresi doldu, revoked İptal edildi), izinleriyle, izinli adresleriyle ve son kullanım zamanıyla listeler.

İzinler

Her anahtara yalnızca sisteminin ihtiyaç duyduğunu verin.

İzinPaneldeki adıAçtığı uç noktalar
customer:readBakiyeleri, ödemeleri ve alıcıları okumaTüm okumalar: GET /v1/customer, /v1/balances, /v1/payouts, /v1/incoming-payouts, /v1/beneficiaries, /v1/receiving, /v1/deposit-instructions, /v1/onboarding, /v1/terms, /v1/end-customers
customer:payouts:createÖdeme oluşturma ve iptal etmePOST /v1/quotes, POST /v1/payouts, POST /v1/payouts/{id}/cancel
customer:beneficiaries:writeAlıcı kaydetmePOST /v1/beneficiaries, POST /v1/beneficiaries/link, POST /v1/receiving/code, PUT /v1/receiving/account
customer:webhooks:manageWebhook'ları yönetmeTüm /v1/webhooks uç noktaları: kaydetme, devre dışı bırakma, etkinleştirme, gizli değeri yenileme, gönderimleri okuma, yeniden gönderme
customer:profile:writeKYC veya KYB tamamlama/v1/profile, /v1/documents, POST /v1/terms
customer:end_customers:manageEnd Customer'ları yönetmePOST /v1/end-customers ve suspend, reactivate işlemleri (yalnızca Platformlar)

Bir anahtar, onu kim oluşturursa oluştursun şu izinleri hiçbir zaman taşımaz:

  • customer:payouts:approve: bekletilen bir ödemeyi onaylamak ya da reddetmek bir kişinin kararıdır ve müşteri panelinde verilir. Bir anahtarın oluşturduğu ödeme, biri onaylayana kadar awaiting_approval durumunda bekleyebilir.
  • customer:rules:manage: onay kuralları panelden düzenlenir.
  • customer:keys:manage ve customer:team:manage: bir anahtar hiçbir zaman anahtar oluşturmaz ya da kişileri yönetmez.

İzinli adresler

İzinli adresler tanımlıysa başka bir adresten gelen istek api_key_ip_denied ile reddedilir. İsteklerinizin çıktığı herkese açık adresleri, her girişe bir IP ya da CIDR aralığı olacak şekilde (en fazla 50) listeleyin; örneğin 203.0.113.7 ya da 198.51.100.0/24. IPv4 ve IPv6 ikisi de desteklenir.

Bitiş ve iptal

Süresi dolan bir anahtar api_key_expired ile reddedilir. Bir anahtarı panelden istediğiniz an iptal edebilirsiniz; o andan itibaren reddedilir ve iptal geri alınamaz.

Anahtarı oluşturan kişi müşteri panelinde devre dışı bırakıldığında o kişinin anahtarları da iptal edilir. Production sistemlerinizin dayandığı anahtarları kalıcı bir yönetici hesabından oluşturun ve biri ayrıldığında anahtar yenilemeyi planlayın.

Anahtarları yenileyin

Ayrı bir yenileme çağrısı yoktur; yenilemeyi örtüşerek yapın:

  1. Aynı izinler ve izinli adreslerle yeni bir anahtar oluşturun.
  2. Yeni anahtarı sistemlerinize dağıtın.
  3. Panelde eski anahtarın "Son kullanım" zamanının ilerlemeyi bıraktığını kontrol edin; bu değer yaklaşık dakikada bir güncellenir.
  4. Eski anahtarı iptal edin.

Anahtarları düzenli aralıklarla, anahtara erişimi olan biri ayrıldığında ve bir anahtarın sızmış olabileceğinden şüphelendiğiniz anda yenileyin.

Bir istek reddedildiğinde

Kimlik doğrulama hataları 401, geçerli ama bu işlem için yetkisi olmayan bir anahtar 403 döner. İkisi de hata zarfını kullanır.

DurumKodAnlamı
401unauthorizedAuthorization başlığı yok ya da bearer token bir API anahtarı değil.
401api_key_invalidAnahtar bilinmiyor, bozuk, diğer ortama ait ya da iptal edilmiş; veya ikinci bir Authorization başlığıyla geldi. Yanıt, bilerek, hangisi olduğunu söylemez.
401api_key_expiredAnahtarın bitiş tarihi geçti.
401api_key_ip_deniedİstek, anahtarın izinli adresleri dışındaki bir adresten geldi.
401api_key_revokedAnahtar iptal edildi. Genellikle bunun yerine api_key_invalid görürsünüz.
403forbiddenAnahtarda bu uç noktanın istediği izin yok.
403customer_suspendedHesabınız askıya alındı. Okumalar çalışır; webhook uç noktalarını devre dışı bırakmak ve End Customer'ları askıya almak dışındaki değişiklikler reddedilir.
403customer_not_activeHesabınız etkin değil (doğrulama sürüyor ya da hesap kapatıldı).
403not_for_end_customersBir End Customer'ın webhook uç noktaları Platformuna aittir.
403people_onlyBu işlemi yalnızca bir kişi yapabilir; örneğin bir End Customer'ın ilk kullanıcısını davet etmek.
401 Unauthorized
{
  "code": "api_key_ip_denied",
  "message": "the API key may not be used from this address",
  "correlation_id": "4a7e2c91-0b5d-4f38-9e16-8c3d2a1f7b05"
}

Bu sayfada