API'yi kendi anahtarlarınızla çağırmak: Evren ve araç sunucuları

Platformdaki bazı modeller ve araç sunucuları sizin kendi anahtarlarınızla çalışır. Evren modelleri sizin Evren anahtarınızı, GitHub, Context7 ve O’Reilly de sizin kendi belirtecinizi kullanır. Bu anahtarları My variables sayfasında saklarsınız ve bir API çağrısı onları asla taşımaz: ağ geçidi bu anahtarları her çağrıda, çağrının kimliğini bildirdiği kişi için okur. Bu yüzden bir betiğin doğru yapması gereken tek şey, kim olduğunu bildirmektir.

Yukarıdaki şekil aynı Evren isteğini aimo’dan, VS Code eklentisinden ve kendi uygulamanızdan karşılaştırıyor. Bu makale API’yi kendi kimliğinizle nasıl çağıracağınızı, anahtarlarınızı nasıl kaydedeceğinizi ve Evren modelleriyle araç sunucularını bu anahtarlarla nasıl kullanacağınızı anlatıyor. Aşağıdaki komutların hepsi 30 Eylül 2026’da canlı bir kurulumda çalıştırıldı; aktarılan yanıtlar da o gün alınanlardır.

Kim ne yapar

Bir çağrı anahtarınızı nasıl bulur

1. Betiğiniz kişisel platform anahtarınızı, gpk_…, Bearer olarak gönderir.
2. Ağ geçidi bu anahtardan sizi tanır. Kotanız, hız limitleriniz ve politikanız uygulanır.
3. Evren anahtarınızı ya da araç değişkeninizi kasanızdan okur.
4. O anahtarı yalnızca bu çağrı için Evren’e ya da araç sunucusuna gönderir.

Betiğiniz yalnızca kişisel platform anahtarını tutar. Bir ekip ya da servis anahtarı bunu yapamaz: bir kişiyi değil bir ekibi temsil eder, dolayısıyla okunacak bir kasa yoktur.

Bölüm A: herkes için, bir kez

A1. Kişisel API anahtarınızı alın

En kısa yol konsoldur. Oturum açın, My variables (/vault) sayfasını açın ve en üstteki My API key kartında Create my API key düğmesine basın.

• Yeni anahtar bir Copy düğmesiyle birlikte görünür. Kabuğunuza BOSPHORUS_KEY adıyla yükleyin.
• Bir kopyası kendi kasanızda saklanır; Show key aynı anahtarı daha sonra yeniden gösterir. Yalnızca size, oturum açtıktan sonra gösterilir.
• Replace yeni bir anahtar verir; eskisi, onu kullanan her betik için hemen çalışmaz olur. Remove anahtarı iptal eder ve kopyayı siler.
• Anahtarın adı user:<adresiniz>#vault olur. Oluşturmak, değiştirmek ya da kaldırmak, düzenleyici eklentinizin ya da ajanlarınızın elindeki anahtarlara asla dokunmaz.

Anahtarı bir parola gibi koruyun: onu elinde tutan herkes sizin adınıza, sizin Evren ve araç anahtarlarınızla işlem yapar. Bu bölümün sonundaki kontrol, iki yoldan alınan anahtar için de çalışır.

Bunun yerine terminalden

Hesabınız konsolu açamıyorsa ya da işi bir betikle yapmak istiyorsanız, anahtarı şirket hesabınızla cihaz kodu kullanarak oturum açıp üretin. curl ve jq gerekir. Önce kurulumunuzun oturum açmayı nasıl sağladığına bakın:

GW=https://ai.corp.example
CFG=$(curl -s $GW/api/identity/config)
echo "$CFG" | jq '{entra: (.entra != null), oidc: .oidc.provider}'

entra değeri true ise kurulum Microsoft Entra ID ile oturum açtırır:

TENANT=$(echo "$CFG" | jq -r .entra.tenantId)
CLIENT=$(echo "$CFG" | jq -r .entra.clientId)
SCOPE=$(echo "$CFG" | jq -r .entra.scope)
DA=https://login.microsoftonline.com/$TENANT/oauth2/v2.0/devicecode
TE=https://login.microsoftonline.com/$TENANT/oauth2/v2.0/token

oidc değeri generic ise kurulum Keycloak gibi kendi OpenID Connect sağlayıcısını kullanır ve uç noktaları da aynı belgede bildirir:

CLIENT=$(echo "$CFG" | jq -r .oidc.clientId)
SCOPE="openid profile email $(echo "$CFG" | jq -r .oidc.apiScope)"
DA=$(echo "$CFG" | jq -r .oidc.endpoints.deviceAuthorization)
TE=$(echo "$CFG" | jq -r .oidc.endpoints.token)

Ardından oturum açmayı başlatın:

DC=$(curl -s $DA -d client_id=$CLIENT --data-urlencode "scope=$SCOPE")
echo "$DC" | jq -r '.message // .verification_uri_complete'

Yazdırılan adresi açın, bir kod gösteriliyorsa girin ve oturum açın. Sonra aynı terminalde belirteci alın ve onu kişisel anahtarınızla takas edin:

TOKEN=$(curl -s $TE -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
  -d client_id=$CLIENT -d device_code=$(echo "$DC" | jq -r .device_code) | jq -r .access_token)
curl -s -X POST "$GW/api/identity/token?client=api" -H "Authorization: Bearer $TOKEN" | jq -r .key.key

• Anahtarın tamamı yalnızca bir kez yazdırılır ve kopyası saklanmaz. Bir parola yöneticisinde saklayın ve kabuğunuza BOSPHORUS_KEY adıyla yükleyin.
• ?client=api bu anahtara kendi adını verir, user:<adresiniz>#api; böylece düzenleyici eklentinizin ya da ajanlarınızın elindeki anahtarlar çalışmaya devam eder.
• Aynı isteği yeniden gönderirseniz yanıt existing key — the full key is shown only at mint; pass ?rotate=true to reissue olur. &rotate=true eklemek bu anahtarı iptal edip yenisini verir; başka hiçbir anahtara dokunmaz.
• Hızlı bir deneme için oturum açma belirtecinin kendisini, $TOKEN, Bearer olarak gönderebilirsiniz. Zaten bir kişisel anahtarınız varsa bu belirteç yaklaşık bir saat boyunca siz olarak tanınır.

Platformun sizi kim olarak gördüğünü kontrol edin:

curl -s $GW/api/identity/me -H "Authorization: Bearer $BOSPHORUS_KEY" | jq .user.email

Komut adresinizi yazdırır. Bir ekip anahtarıyla null yazdırır; yanıttaki note alanında da no user identity presented yazar.

A2. Anahtarlarınızı My variables sayfasına kaydedin

Konsolda oturum açın ve My variables (/vault) sayfasını açın.

• Evren keys: evren_llm_ ile başlayan LLM key değerinizi yapıştırın ve Save düğmesine basın. evren_plt_… ile başlayan Platform key isteğe bağlıdır ve yalnızca bakiyenizi gösterir. evren_mdl_ ile başlayan bir anahtar yanlış türdendir ve kabul edilmez. LLM anahtarınızı kaydettiğinizde Evren’in kullanım koşulları sizin adınıza kabul edilir; Evren koşulların yeni bir sürümünü yayımladığında yeniden kabul edilir. Yöneticiniz bunu kapatabilir.
• Araç sunucuları: kişisel bir değer alan her sunucu, kendi alanıyla listelenir. Kullandığınız her sunucu için değerinizi kaydedin. Zorunlu olanlar, siz kaydedene kadar bunu belirtir.

Evren anahtarı kişisel anahtarınızla bir betikten de yönetilebilir. PUT kaydeder, GET durumu kotanız ve bakiyenizle birlikte gösterir, DELETE siler (yalnızca birini silmek için ?kind=llm ya da ?kind=platform ekleyin):

jq -n --arg k "$EVREN_LLM_KEY" '{api_key: $k}' |
  curl -s -X PUT $GW/api/identity/evren-key \
    -H "Authorization: Bearer $BOSPHORUS_KEY" -H 'Content-Type: application/json' -d @- | jq
curl -s $GW/api/identity/evren-key -H "Authorization: Bearer $BOSPHORUS_KEY" | jq 'keys'

GET yanıtı dört bölümden oluşur: llm, platform, quota ve balance.

Bölüm B: API’yi çağırmak

B1. Evren modelleri

Evren modelleri EV/ önekini taşır. Her çağrı sizin Evren anahtarınızı ve Evren hesabınızın kredilerini kullanır:

curl -s $GW/v1/models -H "Authorization: Bearer $BOSPHORUS_KEY" | jq -r '.data[].id' | grep '^EV/'

curl -s $GW/v1/chat/completions -H "Authorization: Bearer $BOSPHORUS_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"EV/deepseek-v4-flash","messages":[{"role":"user","content":"Merhaba"}]}' \
  | jq -r '.choices[0].message.content'

curl -s $GW/v1/embeddings -H "Authorization: Bearer $BOSPHORUS_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"EV/qwen3-embedding-8b","input":"Merhaba dünya"}' | jq '.data[0].embedding | length'

Bu makalenin yazıldığı gün sohbet Merhaba! Size nasıl yardımcı olabilirim? diye yanıt verdi, gömme vektörü de 4096 boyutluydu. Her yanıtın usage alanında ayrıca bir evren bloğu bulunur: Evren’in ayırdığı ve kalan krediler ile isteğin yönlendirildiği model.

Aynı çağrılar her OpenAI SDK’sından da yapılabilir; yalnızca adres ve anahtar değişir:

import os
from openai import OpenAI

client = OpenAI(base_url="https://ai.corp.example/v1", api_key=os.environ["BOSPHORUS_KEY"])
reply = client.chat.completions.create(
    model="EV/deepseek-v4-flash",
    messages=[{"role": "user", "content": "Merhaba"}],
)
print(reply.choices[0].message.content)

Makalenin yazıldığı gün kullanılabilen Evren modelleri:

Güncel listeyi her zaman /v1/models size gösterir.

B2. Düz HTTP ile bir araç sunucusu

Bir araç çağrısı tek bir POST isteğidir: aracın argümanları JSON gövdesidir; istek sunucuya giderken ağ geçidi değerinizi kasanızdan ekler. Aşağıdaki istek O’Reilly’de sizin kendi belirtecinizle arama yapar:

curl -s -X POST $GW/api/mcp/oreilly/tools/search_oreilly_content \
  -H "Authorization: Bearer $BOSPHORUS_KEY" -H 'Content-Type: application/json' \
  -d '{"query":"kubernetes networking"}' | jq '{isError, result: (.result | .[0:200])}'

Yanıt {"result": "…", "isError": false} biçimindedir. Bir sunucunun araçlarını ve argümanlarını görmek için aynı anahtarla tanımını okuyun:

curl -s $GW/api/mcp/oreilly/openapi.json -H "Authorization: Bearer $BOSPHORUS_KEY" | jq '.paths | keys'

O’Reilly için tek bir yol listelenir: /tools/search_oreilly_content.

B3. Bir MCP istemcisinden araç sunucusu

Claude Code gibi MCP istemcileri aktarıcının adresini ve aynı anahtarı kullanır. Dosyaya hiçbir araç belirteci yazılmaz:

"oreilly": {
  "type": "http",
  "url": "https://ai.corp.example/api/mcp/oreilly",
  "headers": {
    "Authorization": "Bearer ${BOSPHORUS_KEY}"
  }
}

VS Code için aimo eklentisinde yapılandıracak bir şey yoktur: oturum açtığınızda aynı sunuculara aynı yoldan ulaşır.

Hangi kimlik bilgisini göndermelisiniz

Platformun anahtarlarınız için verdiği sözler

• Bir anahtar sizin her çağrınızda sizin kasanızdan okunur ve yalnızca ait olduğu sağlayıcıya ya da sunucuya gönderilir. Önbellek yoktur: bir değişiklik bir sonraki çağrıda geçerli olur.
• Anahtar hiçbir zaman modelin bağlamına, bir günlük satırına ya da denetim izine girmez. Bir araç çağrısının denetim kaydı yalnızca değişkenin adını tutar.
• Araç sunucusu değerleri, kurulumunuz OpenBao çalıştırıyorsa kendi OpenBao klasörünüzde, çalıştırmıyorsa platform veritabanında mühürlü olarak saklanır. Evren anahtarları platform veritabanında şifreli olarak saklanır.
• Model çağrıları kotanızdan ve hız limitlerinizden düşer. Model çağrıları da araç çağrıları da etkinlik sayfasında sizin adınızla görünür.
• Kişisel platform anahtarınız, sizin anahtarlarınızla sizin adınıza işlem yapar. Onu bir parola gibi koruyun; sızmış olabileceğini düşünüyorsanız yenileyin.

Bir şey yolunda gitmediğinde