# Kimlik doğrulama ve anahtarlar

Sayfa: https://docs.sonecentral.com/kimlik-dogrulama
Markdown: https://docs.sonecentral.com/kimlik-dogrulama.md

> Sunucu anahtarı ile tarayıcı anahtarı arasındaki fark, anahtarın nasıl gönderildiği, izin verilen siteler ve anahtarın nasıl iptal edildiği.

## İki anahtar türü

| | Sunucu anahtarı | Tarayıcı anahtarı |
| --- | --- | --- |
| Biçim | `sk-sone-v1-` ve 48 harf ya da rakam | `pk-sone-v1-` ve 48 harf ya da rakam |
| Nerede | Arka uç kodu, sunucusuz işlev, betik | Sitenizdeki sohbet penceresi |
| Tarayıcıdan | Reddedilir (`403 secret_key_in_browser`) | Yalnız izin verilen sitelerden |
| `user` ile sohbet bulma | Var | Yok, gönderilen değer yok sayılır |
| Geliştirici bağlamı | Var | Yok, gönderilen bağlam yok sayılır |
| Yeni sohbete aktarılan geçmiş | Ziyaretçi ve asistan satırları | Yalnız ziyaretçinin satırları |
| İstek sınırı | Anahtar başına dakikada 120 | Ziyaretçi adresi başına dakikada 30; anahtar başına saatte 1.200 istek ve 20.000 okuma |
| Otomatik yanıt sınırı | Çalışma alanının sınırı: saatte 60, günde 300 tur | Bu sınırın içinde bütün tarayıcı anahtarlarının ortak payı: saatte 40, günde 200 tur |

Anahtarları Sonecentral'da **Metin asistanı** sayfasının **API anahtarları** bölümünde oluşturur, düzenler ve iptal edersiniz. Bu bölümü yalnız çalışma alanının yöneticileri görür. Bir çalışma alanında aynı anda en fazla 50 etkin anahtar olabilir; iptal edilen anahtarlar bu sayıya girmez.

## Anahtarı göndermek

Anahtarı `Authorization` başlığında taşıyın:

```http
Authorization: Bearer sk-sone-v1-...
```

`x-api-key` başlığı da kabul edilir. İkisi birden gelirse `Authorization` kullanılır.

```http
x-api-key: sk-sone-v1-...
```

OpenAI SDK'ları ve Vercel AI SDK, `apiKey` seçeneğine verdiğiniz değeri zaten `Authorization: Bearer` olarak gönderir.

## Anahtar ne zaman gösterilir

Anahtarın tamamı yalnız oluşturulduğu anda, bir kez gösterilir. Sonecentral onu saklamaz, yalnız özetini tutar; listede ilk karakterleri ve son dört karakteri görürsünüz. İstek kayıtlarımız da anahtarı tutmaz; `Authorization` ile de, `x-api-key` ile de gönderilse. Anahtarı kaybettiyseniz yenisini oluşturup eskisini iptal edin.

## Anahtarın ayarları

Anahtar oluşturulurken şunlar seçilir:

- **Ad.** Anahtarı listede tanımanız için, en fazla 80 karakter. `GET /key` yanıtında da görünür; gizli bilgi yazmayın.
- **Tür.** Sunucu anahtarı ya da tarayıcı anahtarı. Tür sonradan değiştirilemez; gerekirse yeni anahtar oluşturun.
- **Asistanlar.** Anahtarın çağırabileceği asistanlar. Hepsi seçilirse çalışma alanında yayında olan bütün asistanlar, sonradan yayınlananlar da. Henüz yayında olmayan bir asistan da seçilebilir; anahtar onunla asistan yayınlandığında çalışır.
- **İzin verilen siteler.** Yalnız tarayıcı anahtarında. En az bir, en fazla 20 site.
- **Sipariş ve randevu talebi alabilir.** Açıksa asistan bu sohbetlerde yeni sipariş ya da randevu talebi açabilir; talepler ekibinizin onayını bekler. Kapalıysa asistan isteği ayrıntılarıyla ekibe iletir. Varsayılan olarak açıktır. Ayrıntılar: [Siparişler, randevular ve gizlilik](https://docs.sonecentral.com/siparis-randevu-gizlilik.md).

Tür dışındaki ayarlar sonradan düzenlenebilir; değişiklik bir sonraki istekte geçerli olur.

## İzin verilen siteler

Tarayıcı, siteler arası her istekte `Origin` başlığını kendisi gönderir. Tarayıcı anahtarı yalnız `Origin` değeri listedeki sitelerden biriyle aynıysa kabul edilir. `Origin` başlığı olmayan bir istekte tarayıcı anahtarı kullanılamaz.

Site adresleri şöyle yazılır:

- `https://www.ornek.com` gibi, yalnız şema ve alan adı. Alan adında en az bir nokta olmalıdır. 443 dışında bir port gerekiyorsa `https://www.ornek.com:8443` gibi yazılır.
- Yol, sorgu, `*` joker karakteri, IP adresi ve `https://localhost` kabul edilmez.
- `https://ornek.com` ile `https://www.ornek.com` iki ayrı sitedir; ikisini de kullanıyorsanız ikisini de ekleyin.
- Geliştirme için yalnız `http://localhost` ve `http://127.0.0.1` eklenebilir, portlu ya da portsuz: `http://localhost:3000`, `http://127.0.0.1:5173`. Bunun dışında `http` kabul edilmez.

Alan adı küçük harfe çevrilerek karşılaştırılır. Listede olmayan bir siteden gelen istek `403 origin_not_allowed` ile reddedilir.

## Sunucu anahtarı tarayıcıda çalışmaz

Sunucu anahtarı sitenizin koduna girerse onu herkes okuyabilir ve sizin adınıza istek gönderebilir. Bunun önüne geçmek için Sonecentral, `Origin` başlığında anahtarın listelemediği bir site taşıyan istekte sunucu anahtarını `403 secret_key_in_browser` ile reddeder. Panel sunucu anahtarına site eklemez; bu yüzden tarayıcıdan gelen her istek reddedilir. Tarayıcıda her zaman tarayıcı anahtarını kullanın.

Bu bir güvenlik ağıdır, garanti değildir. Bilgisayardaki bir dosyadan ya da korumalı bir çerçeveden açılan sayfalar `Origin: null` gönderir. Sonecentral böyle bir isteği sunucudan gelen bir istekten ayıramaz ve reddetmez. Sunucu anahtarını tarayıcıya, mobil uygulama paketine ya da herkese açık bir depoya hiçbir zaman koymayın.

> **Dikkat**
>
> OpenAI SDK'sının `dangerouslyAllowBrowser` seçeneği bu kuralı aşmaz. Tarayıcıda sunucu anahtarı yerine tarayıcı anahtarı kullanın.

Tarayıcıdaki kodunuz yanıtın şu başlıklarını okuyabilir: `x-request-id`, `retry-after`, `x-should-retry` ve `x-sone-conversation-id`.

## Geliştirici bağlamı

Sunucu anahtarıyla gönderdiğiniz `system` ve `developer` rolündeki mesajlar, Responses'taki `instructions` alanı ve Vercel AI SDK'daki `context` alanı asistana **yalnız bilgi olarak** iletilir. Örneğin ziyaretçinin hangi ürün sayfasında olduğunu ya da uygulamanızdaki dil tercihini bildirebilirsiniz.

Bu metin işletmenin talimatını ve kurallarını değiştiremez; içindeki talimatlara uyulmaz. Birden çok bağlam alt alta birleştirilir ve en fazla 2.000 karakteri dikkate alınır. Responses'taki `instructions` 2.000 karakterden ya da JSON olarak 4 KB'tan uzunsa istek `400 instructions_too_long` alır. Bağlam, gönderildiği tur için geçerlidir: sonraki istekte göndermezseniz kalkar.

Tarayıcı anahtarıyla gönderilen geliştirici bağlamı yok sayılır ve saklanmaz, çünkü onu ziyaretçi de değiştirebilir.

## İptal

Anahtarı **API anahtarları** bölümünden iptal ettiğiniz anda kullanılamaz olur; sonraki istekler `401 revoked_api_key` alır. İptal geri alınmaz, iptal edilen anahtar düzenlenemez; gerekirse yeni anahtar oluşturun. Anahtarın açtığı sohbetler Mesajlar ekranında kalır.

İptal edilen anahtarın sakladığı yanıtlar 30 gün sonra kendiliğinden silinir. Aynı asistanı çağırabilen yeni bir anahtar onları okuyabilir ve `previous_response_id` ile sürdürebilir, ama silemez; `instructions`, `safety_identifier` ve `user` alanlarını da göremez: [Saklanan yanıtlar](https://docs.sonecentral.com/responses.md#saklanan-yanitlar).

## Anahtarı denetlemek

`GET /key` kullandığınız anahtarın özetini döner. Anahtarın doğru çalışma alanına ve asistanlara bağlı olduğunu kurulumda bununla doğrulayabilirsiniz.

```bash
curl https://pb.sonecentral.com/api/v1/key \
  -H "Authorization: Bearer $SONE_API_KEY"
```

```json
{
  "data": {
    "label": "pk-sone-v1-Ab3…",
    "name": "Web sitesi sohbeti",
    "kind": "publishable",
    "assistants": ["k3m9x2p7q1w8e4r"],
    "requests": true,
    "allowed_origins": ["https://www.ornek.com"],
    "limits": {
      "requests_per_minute_per_visitor": 30,
      "requests_per_hour": 1200,
      "read_requests_per_hour": 20000,
      "assistant_turns_per_hour": 60,
      "assistant_turns_per_day": 300,
      "browser_assistant_turns_per_hour": 40,
      "browser_assistant_turns_per_day": 200
    }
  }
}
```

| Alan | Tür | Açıklama |
| --- | --- | --- |
| `label` | string | Anahtarın ilk 14 karakteri ve üç nokta. Anahtarın tamamı hiçbir yanıtta yer almaz. |
| `name` | string | Anahtara Sonecentral'da verdiğiniz ad. |
| `kind` | "secret" \| "publishable" | secret sunucu anahtarı, publishable tarayıcı anahtarıdır. |
| `assistants` | string[] | Anahtarın şu an çağırabildiği, yayında olan asistanların kimlikleri, adlarına göre sıralı. |
| `requests` | boolean | Sipariş ve randevu talebi alabilir ayarı açık mı. |
| `allowed_origins` | string[] | İzin verilen siteler. Sunucu anahtarında boştur. |
| `limits` | object | Sunucu anahtarında requests_per_minute. Tarayıcı anahtarında requests_per_minute_per_visitor, requests_per_hour (okuma dışındaki istekler), read_requests_per_hour (okumalar) ve tarayıcı anahtarlarının otomatik yanıt payı: browser_assistant_turns_per_hour ve browser_assistant_turns_per_day. İkisinde de çalışma alanının API için saatlik ve günlük otomatik yanıt sınırı: assistant_turns_per_hour ve assistant_turns_per_day. |

Sunucu anahtarında `limits` şöyledir:

```json
{ "requests_per_minute": 120, "assistant_turns_per_hour": 60, "assistant_turns_per_day": 300 }
```

`GET /key` isteği de bir okumadır ve anahtarın sınırına sayılır: [Limitler](https://docs.sonecentral.com/limitler.md).

## Hatalar

| Durum | `code` | Ne zaman |
| --- | --- | --- |
| `401` | `missing_api_key` | Anahtar gönderilmedi. |
| `401` | `invalid_api_key` | Anahtar tanınmadı, biçimi bozuk ya da öneki türüyle uyuşmuyor. |
| `401` | `revoked_api_key` | Anahtar iptal edilmiş. |
| `403` | `origin_not_allowed` | Tarayıcı anahtarı listede olmayan bir siteden ya da `Origin` başlığı olmadan kullanıldı. |
| `403` | `secret_key_in_browser` | Sunucu anahtarı, anahtarın listelemediği bir sitedeki tarayıcıdan kullanıldı. |
| `429` | `rate_limit_exceeded` | Anahtarın istek ya da okuma sınırı aşıldı. `Retry-After` kadar bekleyin. |

Bütün hata kodları: [Hatalar](https://docs.sonecentral.com/hatalar.md).