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 "$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:
| Alan | Ne işe yarar |
|---|---|
| Ad | Anahtarı neyin kullanacağı, örneğin "ERP senkronu". |
| İzinler | Anahtarı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.
| İzin | Paneldeki adı | Açtığı uç noktalar |
|---|---|---|
customer:read | Bakiyeleri, ödemeleri ve alıcıları okuma | Tü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 etme | POST /v1/quotes, POST /v1/payouts, POST /v1/payouts/{id}/cancel |
customer:beneficiaries:write | Alıcı kaydetme | POST /v1/beneficiaries, POST /v1/beneficiaries/link, POST /v1/receiving/code, PUT /v1/receiving/account |
customer:webhooks:manage | Webhook'ları yönetme | Tüm /v1/webhooks uç noktaları: kaydetme, devre dışı bırakma, etkinleştirme, gizli değeri yenileme, gönderimleri okuma, yeniden gönderme |
customer:profile:write | KYC veya KYB tamamlama | /v1/profile, /v1/documents, POST /v1/terms |
customer:end_customers:manage | End Customer'ları yönetme | POST /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 kadarawaiting_approvaldurumunda bekleyebilir.customer:rules:manage: onay kuralları panelden düzenlenir.customer:keys:managevecustomer: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:
- Aynı izinler ve izinli adreslerle yeni bir anahtar oluşturun.
- Yeni anahtarı sistemlerinize dağıtın.
- 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.
- 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.
| Durum | Kod | Anlamı |
|---|---|---|
| 401 | unauthorized | Authorization başlığı yok ya da bearer token bir API anahtarı değil. |
| 401 | api_key_invalid | Anahtar 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. |
| 401 | api_key_expired | Anahtarın bitiş tarihi geçti. |
| 401 | api_key_ip_denied | İstek, anahtarın izinli adresleri dışındaki bir adresten geldi. |
| 401 | api_key_revoked | Anahtar iptal edildi. Genellikle bunun yerine api_key_invalid görürsünüz. |
| 403 | forbidden | Anahtarda bu uç noktanın istediği izin yok. |
| 403 | customer_suspended | Hesabı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. |
| 403 | customer_not_active | Hesabınız etkin değil (doğrulama sürüyor ya da hesap kapatıldı). |
| 403 | not_for_end_customers | Bir End Customer'ın webhook uç noktaları Platformuna aittir. |
| 403 | people_only | Bu işlemi yalnızca bir kişi yapabilir; örneğin bir End Customer'ın ilk kullanıcısını davet etmek. |
{
"code": "api_key_ip_denied",
"message": "the API key may not be used from this address",
"correlation_id": "4a7e2c91-0b5d-4f38-9e16-8c3d2a1f7b05"
}