> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Orbit API isteklerini anahtarlar ve token'larla doğrulama

> Orbit API isteklerini sunucudan sunucuya çağrılar için API anahtarları veya Bearer oturum token'larıyla, ayrıca kurumsal kontrol paneli kullanıcıları için SAML SSO ile doğrulayın.

# Kimlik Doğrulama

Orbit, **API isteklerini** iki şekilde doğrular: sunucudan sunucuya çağrılar için
bir API anahtarı ve kontrol paneli kullanıcıları için bir oturum Bearer token'ı.
Kurumsal kuruluşlar ayrıca kullanıcılarını [SAML çoklu oturum açma](#single-sign-on-saml)
üzerinden oturum açtırabilir ve [SCIM](#directory-provisioning-scim) aracılığıyla
sağlayabilir. İsteğin nasıl yapıldığına uyan yöntemi seçin.

## API Anahtarı (Sunucudan Sunucuya)

API anahtarınızı `X-API-Key` başlığına ekleyin:

```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/messages \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

## Bearer Token (Kontrol Paneli Kullanıcıları)

Kontrol paneli kullanıcıları için JWT Bearer token'ları kullanın:

```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/messages \
  -H "Authorization: Bearer eyJhbG..."
```

<Note>
  API anahtarını ayrıca `Authorization: Bearer dv_live_pk_...` (herhangi bir
  `dv_` anahtarı — `dv_live_sk_`, `dv_test_sk_`, `dv_live_pk_`, `dv_test_pk_`)
  olarak da iletebilirsiniz; bu, `X-API-Key` özel başlığının CORS tarafından
  engellendiği ortamlar için geçerlidir. Sunucu her iki biçimi de kabul eder:
  önce `X-API-Key` başlığını okur, ardından `dv_` öneki taşıyan bir `Bearer`
  token'ına geri döner. Bir JWT (`eyJ` ile başlar) hâlâ kontrol paneli oturum
  token'ı olarak ele alınır, bu nedenle ikisi asla çakışmaz.
</Note>

## API Anahtarı Biçimi

| Tür         | Önek          | Kullanım                                |
| ----------- | ------------- | --------------------------------------- |
| Canlı Gizli | `dv_live_sk_` | Sunucu tarafı API çağrıları             |
| Test Gizli  | `dv_test_sk_` | Sunucu tarafı API çağrıları (test modu) |
| Canlı Genel | `dv_live_pk_` | İstemci tarafı (tarayıcı SDK'ları)      |
| Test Genel  | `dv_test_pk_` | İstemci tarafı (test modu)              |

<Warning>
  Genel bir anahtar (`dv_live_pk_` / `dv_test_pk_`), istemci tarafı koda
  gömülmek üzere tasarlanmıştır; bu nedenle oluşturma sırasında **yalnızca
  salt okunur kapsamlarla sınırlandırılır**. Yazma ve yönetim kapsamları —
  `messages:write`, `contacts:write`, `admin`, `*` joker karakteri ve hassas
  hesap okumaları `billing:read` / `settings:read` — genel bir anahtar için
  `422` hatasıyla reddedilir. Veri gönderen veya değiştiren herhangi bir işlem
  için bir **gizli anahtar** (`dv_live_sk_`) kullanın.

  Yine de tarayıcıya veya mobil pakete gönderdiğiniz her anahtarı herkese açık
  olarak görünür kabul edin ve ihtiyaç duyduğu minimum okumalarla sınırlandırın.
</Warning>

## Çoklu oturum açma (SAML)

Kurumsal kuruluşlar, kontrol paneli kullanıcılarını SAML 2.0 kimlik sağlayıcısı
üzerinden — Okta, Microsoft Entra ID (eski adıyla Azure AD), OneLogin, Google
Workspace veya PingFederate — oturum açtırabilir. SSO, kişileri kontrol
paneline doğrular; API anahtarları oluşturmaz, bu nedenle sunucudan sunucuya
çağrılar yine yukarıdaki yöntemleri kullanır.

Bir sahip, kontrol panelinde **Ayarlar → Çoklu oturum açma** altında (veya
`PATCH /api/v1/settings/saml` aracılığıyla) bağlantıyı yapılandırır: IdP'nizin
SSO URL'sini, varlık kimliğini ve imzalama sertifikasını ayarlayın, ardından
etkinleştirmeden önce **Bağlantıyı test et** seçeneğini kullanın.

Her kuruluş, kuruluş slug'ınıza (`orgSlug`) bağlı kendi uç noktaları kümesine
sahiptir. Bunlar API kökünde bulunur, `/api/v1` altında **değil**:

| Yöntem | Uç Nokta                        | Amaç                                                                     |
| ------ | ------------------------------- | ------------------------------------------------------------------------ |
| GET    | `/auth/saml/{orgSlug}/metadata` | IdP'nize aktarılacak hizmet sağlayıcı metadata XML'i                     |
| GET    | `/auth/saml/{orgSlug}/login`    | SSO akışını başlatır (IdP'nize yönlendirir)                              |
| POST   | `/auth/saml/{orgSlug}/callback` | Assertion Consumer Service (ACS) — IdP'niz imzalı yanıtı buraya gönderir |
| GET    | `/auth/saml/{orgSlug}/logout`   | Tekli oturum kapatmayı başlatır                                          |

IdP'nizi metadata uç noktasına yönlendirin; örneğin `acme` kuruluşu için
`https://api.orbit.devotel.io/auth/saml/acme/metadata`.

## Dizin sağlama (SCIM)

Kontrol paneli kullanıcılarını kimlik sağlayıcınızdan SCIM 2.0 üzerinden
otomatik olarak sağlayın ve kaldırın. **Ayarlar → SCIM** altında (veya
`POST /api/v1/settings/scim/generate-token` aracılığıyla) bir sağlama token'ı
oluşturun — token yalnızca bir kez gösterilir, bu nedenle hemen IdP'nize
kopyalayın.

IdP'niz token'ı her istekte Bearer kimlik bilgisi olarak gönderir:

```bash theme={null}
curl https://api.orbit.devotel.io/scim/v2/acme/Users \
  -H "Authorization: Bearer <your-scim-token>"
```

Uç noktalar SCIM 2.0 spesifikasyonunu izler ve `application/scim+json`
döndürür. Kuruluş slug'ınıza bağlıdır ve API kökünde bulunur, `/api/v1`
altında **değil**:

| Kaynak       | Uç Noktalar                                                                                                        |
| ------------ | ------------------------------------------------------------------------------------------------------------------ |
| Kullanıcılar | `/scim/v2/{orgSlug}/Users` (listeleme, oluşturma), `/scim/v2/{orgSlug}/Users/{id}` (alma, değiştirme, yama, silme) |
| Gruplar      | `/scim/v2/{orgSlug}/Groups` (listeleme, oluşturma/güncelleme), `/scim/v2/{orgSlug}/Groups/{id}` (alma)             |
| Keşif        | `/scim/v2/{orgSlug}/ServiceProviderConfig`, `/ResourceTypes`, `/Schemas`                                           |

<Note>
  SAML ve SCIM bağımsızdır: SSO kullanıcıların nasıl oturum açtığını, SCIM
  hangi kullanıcıların var olduğunu kontrol eder. İkisini de ayrı ayrı
  etkinleştirebilirsiniz, ancak çoğu IdP ikisini birlikte yapılandırır.
</Note>

Tam sağlama kılavuzu için — temel URL oluşturma, rol eşleme, IdP sağlık
kontrolleri ve Okta / Entra / genel istemci adımları —
[SCIM 2.0 sağlama kılavuzuna](/compliance/scim-provisioning) bakın.