---
title: "MCP istemcileri için OAuth"
description: "Kullanıcıları TwexAPI'ye giriş yaptıran bir MCP istemcisi geliştirmek için referans: keşif, dinamik istemci kaydı, PKCE, scope'lar, token'lar, yenileme ve iptal."
---

TwexAPI, MCP sunucusu için bir OAuth 2.1 yetkilendirme sunucusu çalıştırır. Claude, ChatGPT ve Cursor gibi MCP istemcileri bunu otomatik olarak kullanır. Kendi istemcinizi geliştirirken veya bir istemcide hata ayıklarken bu sayfayı kullanın.

- PKCE ile yetkilendirme kodu akışı (yalnızca `S256`).
- Yalnızca public istemciler, client secret yok. Dinamik istemci kaydıyla (RFC 7591) kaydolun.
- Kullanıcılar TwexAPI hesaplarıyla giriş yapar ve erişimi `https://twexapi.io/oauth/consent` adresinde onaylar.
- Token'lar yalnızca `https://api.twexapi.io/mcp` üzerinde çalışan opak dizelerdir. TwexAPI API anahtarı değildirler ve REST API'yi çağıramazlar.
- Çağrılar kullanıcının API anahtarı üzerinden kullanıcının kredilerinden düşülür; bu nedenle onay için kredisi olan etkin bir anahtar gerekir.

TwexAPI'yi yalnızca bir script'ten veya backend'den çağırmak istiyorsanız bir [API anahtarı](/authentication) kullanın.

## Keşif

`https://api.twexapi.io/mcp` adresine kimlik bilgisi olmadan yapılan istek, şu header ile `401` döndürür:

```http
WWW-Authenticate: Bearer realm="twexapi", resource_metadata="https://api.twexapi.io/.well-known/oauth-protected-resource/mcp", scope="mcp:read mcp:write"
```

### Korunan kaynak meta verisi

`GET https://api.twexapi.io/.well-known/oauth-protected-resource/mcp` (`/.well-known/oauth-protected-resource` adresinde de aynısı):

```json
{
  "resource": "https://api.twexapi.io/mcp",
  "authorization_servers": ["https://api.twexapi.io"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["mcp:read", "mcp:write"],
  "resource_name": "TwexAPI"
}
```

### Yetkilendirme sunucusu meta verisi

`GET https://api.twexapi.io/.well-known/oauth-authorization-server`:

```json
{
  "issuer": "https://api.twexapi.io",
  "authorization_endpoint": "https://api.twexapi.io/oauth/authorize",
  "token_endpoint": "https://api.twexapi.io/oauth/token",
  "registration_endpoint": "https://api.twexapi.io/oauth/register",
  "revocation_endpoint": "https://api.twexapi.io/oauth/revoke",
  "response_types_supported": ["code"],
  "response_modes_supported": ["query"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "revocation_endpoint_auth_methods_supported": ["none"],
  "scopes_supported": ["mcp:read", "mcp:write"],
  "authorization_response_iss_parameter_supported": true
}
```

<a id="scopes"></a>

## Scope'lar

| Scope | İzin verir |
| --- | --- |
| `mcp:read` | `explore` ve `twexapi_request` (salt okunur uç noktalar). Her zaman verilir. |
| `mcp:write` | `twexapi_write` (tweet ve yanıt paylaşma). Kullanıcı onay sayfasında bunu reddedebilir. |

İkisini birden istemek için `mcp:read mcp:write` isteyin. Bilinmeyen scope'lar yok sayılır; tanınan hiçbir scope yoksa istek ikisini birden istiyormuş gibi değerlendirilir. Token yanıtındaki `scope` alanı, kullanıcının gerçekte neye izin verdiğini gösterir.

## 1. İstemci kaydedin

```http
POST https://api.twexapi.io/oauth/register
Content-Type: application/json

{
  "client_name": "My Agent",
  "redirect_uris": ["http://127.0.0.1:53682/callback"]
}
```

```json
{
  "client_id": "twx_client_...",
  "client_id_issued_at": 1792600000,
  "client_name": "My Agent",
  "redirect_uris": ["http://127.0.0.1:53682/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}
```

| Alan | Kurallar |
| --- | --- |
| `redirect_uris` | Zorunlu. 1 ila 10 URI; her biri şunlardan biri olmalıdır: `https://`, `localhost`, `127.0.0.1` veya `[::1]` üzerinde `http://`, ya da `cursor://` gibi özel bir şema. Fragment veya kullanıcı bilgisi içeremez. |
| `client_name` | İsteğe bağlı, en fazla 100 karakter. Onay sayfasında ve kullanıcının **Authorized apps** (yetkili uygulamalar) listesinde gösterilir. |
| `token_endpoint_auth_method` | İsteğe bağlı. Yalnızca `none` kabul edilir. |
| `grant_types` | İsteğe bağlı. `authorization_code` ve `refresh_token` değerlerinin bir alt kümesi. |
| `response_types` | İsteğe bağlı. Yalnızca `code` kabul edilir. |

Kayıt, IP adresi başına saatte 30 istemciyle sınırlıdır. Bir istemci kaydı 180 gün geçerlidir ve bir kullanıcı onunla her yetkilendirme başlattığında uzatılır. Bir kez kaydolun ve `client_id` değerini yeniden kullanın.

## 2. PKCE çifti oluşturun

Node.js:

```js
import crypto from "node:crypto";

const verifier = crypto.randomBytes(32).toString("base64url");
const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");
```

Python:

```python
import base64, hashlib, secrets

verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b"=").decode()
challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()
```

Verifier, `A-Z a-z 0-9 - . _ ~` karakterlerinden oluşan 43 ila 128 karakter olmalıdır.

## 3. Kullanıcıyı yetkilendirmeye gönderin

Bu URL'yi kullanıcının tarayıcısında açın:

```txt
https://api.twexapi.io/oauth/authorize
  ?response_type=code
  &client_id=twx_client_...
  &redirect_uri=http%3A%2F%2F127.0.0.1%3A53682%2Fcallback
  &code_challenge=CHALLENGE
  &code_challenge_method=S256
  &state=RANDOM_STATE
  &scope=mcp%3Aread%20mcp%3Awrite
  &resource=https%3A%2F%2Fapi.twexapi.io%2Fmcp
```

| Parametre | Zorunlu | Notlar |
| --- | --- | --- |
| `response_type` | Evet | `code`. |
| `client_id` | Evet | Kayıttan alınır. |
| `redirect_uri` | Evet | Kayıtlı bir URI ile tam olarak eşleşmelidir. Loopback `http` URI'leri her portu kabul eder. |
| `code_challenge`, `code_challenge_method` | Evet | Yalnızca `S256`. |
| `state` | Önerilir | Değiştirilmeden geri döner. CSRF'ye karşı doğrulayın. |
| `scope` | Hayır | Bkz. [Scope'lar](#scopes). |
| `resource` | Hayır | Gönderilirse `https://api.twexapi.io/mcp` olmalıdır. |

TwexAPI kullanıcıyı `twexapi.io` üzerindeki onay sayfasına gönderir. Kullanıcı giriş yapar, uygulama adını ve geri döneceği host'u görür, yazma erişimi verip vermeyeceğini seçer ve onaylar ya da reddeder. İsteğin süresi 10 dakika sonra dolar.

## 4. Kodu alın

Onaydan sonra tarayıcı yönlendirme URI'nize geri döner:

```txt
http://127.0.0.1:53682/callback?code=CODE&state=RANDOM_STATE&iss=https%3A%2F%2Fapi.twexapi.io
```

`state` değerinin eşleştiğini ve `iss` değerinin `https://api.twexapi.io` olduğunu kontrol edin. Kullanıcı reddederse `code` yerine `error=access_denied` alırsınız. Kod tek kullanımlıktır ve 2 dakika sonra süresi dolar.

`client_id` bilinmiyorsa veya `redirect_uri` kayıtlı değilse TwexAPI yönlendirme yapmak yerine bir `400` hatası gösterir; böylece yanlış yapılandırılmış bir istemci kullanıcıyı asla doğrulanmamış bir adrese göndermez.

## 5. Kodu token'larla değiştirin

```http
POST https://api.twexapi.io/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=CODE
&redirect_uri=http%3A%2F%2F127.0.0.1%3A53682%2Fcallback
&client_id=twx_client_...
&code_verifier=VERIFIER
```

```json
{
  "access_token": "twx_at_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "twx_rt_...",
  "scope": "mcp:read mcp:write"
}
```

`redirect_uri` ve `client_id`, yetkilendirme isteğiyle eşleşmelidir. `resource=https://api.twexapi.io/mcp` da gönderebilirsiniz. JSON gövdeleri kabul edilir.

## 6. MCP sunucusunu çağırın

```http
POST https://api.twexapi.io/mcp
Authorization: Bearer twx_at_...
Content-Type: application/json
Accept: application/json, text/event-stream
```

Erişim token'ları yalnızca `/mcp` üzerinde çalışır. Süresi dolmuş, iptal edilmiş veya bilinmeyen bir token, `WWW-Authenticate` header'ında `error="invalid_token"` ile `401` alır. Token'ı yenileyin veya kullanıcıdan yeniden giriş yapmasını isteyin.

## Token'ları yenileme

```http
POST https://api.twexapi.io/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=twx_rt_...
&client_id=twx_client_...
```

Her yenileme yeni bir erişim token'ı ve yeni bir refresh token döndürür; eski refresh token artık çalışmaz. Her seferinde yeni çifti saklayın. Eski bir refresh token yeniden kullanılırsa TwexAPI bunu sızdırılmış kabul eder ve yetkilendirmenin tamamını iptal eder: tüm token'ları çalışmayı bırakır ve kullanıcının yeniden giriş yapması gerekir.

## İptal

```http
POST https://api.twexapi.io/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=twx_rt_...
```

Bir refresh token'ı iptal etmek tüm yetkilendirmeyi sonlandırır. Bir erişim token'ını iptal etmek yalnızca o token'ı geçersiz kılar. Uç nokta, bilinmeyen token'lar için bile her zaman `200` döndürür. Kullanıcılar bir uygulamayı [paneldeki](https://twexapi.io/dashboard) **Authorized apps** (yetkili uygulamalar) altından da iptal edebilir; bu hemen geçerli olur.

## Token süreleri

| Öğe | Süre |
| --- | --- |
| Yetkilendirme isteği (onay sayfası) | 10 dakika |
| Yetkilendirme kodu | 2 dakika, tek kullanımlık |
| Erişim token'ı | 1 saat |
| Refresh token | 30 gün, her kullanımda yenilenir |
| 30 gün kullanılmayan yetkilendirme | Süresi dolar |
| İstemci kaydı | 180 gün, her yetkilendirmede uzatılır |

## Hatalar

Hatalar standart OAuth biçimini kullanır:

```json
{
  "error": "invalid_grant",
  "error_description": "The authorization code is invalid, expired or already used"
}
```

| Uç nokta | `error` | Neden |
| --- | --- | --- |
| Kayıt | `invalid_redirect_uri` | Yönlendirme URI'si eksik veya hatalı, ya da izin verilmeyen bir şema veya host kullanıyor. |
| Kayıt | `invalid_client_metadata` | Desteklenmeyen `token_endpoint_auth_method`, `grant_types` veya `response_types`. |
| Kayıt | `temporarily_unavailable` (`429`) | IP adresinizden çok fazla kayıt yapıldı. `client_id` değerinizi yeniden kullanın. |
| Yetkilendirme | `invalid_client` (`400`, yönlendirme yok) | Bilinmeyen `client_id`. Önce kaydolun. |
| Yetkilendirme | `invalid_request` (`400`, yönlendirme yok) | `redirect_uri` bu istemci için kayıtlı değil. |
| Yetkilendirme | `unsupported_response_type` | `response_type`, `code` değil. |
| Yetkilendirme | `invalid_request` | PKCE parametreleri eksik veya geçersiz. |
| Yetkilendirme | `invalid_target` | `resource`, `https://api.twexapi.io/mcp` değil. |
| Yetkilendirme | `access_denied` | Kullanıcı erişimi reddetti. |
| Token | `invalid_grant` | Kod veya refresh token geçersiz, süresi dolmuş, zaten kullanılmış ya da başka bir istemciye verilmiş; veya PKCE doğrulaması başarısız oldu; veya yetkilendirme iptal edildi. |
| Token | `invalid_target` | `resource` eşleşmiyor. |
| Token | `unsupported_grant_type` | `authorization_code` veya `refresh_token` kullanın. |

Kullanıcının hesabında etkin bir API anahtarı veya kredi yoksa onay sayfası onaydan önce bunu engeller; böylece istemciniz çağrı yapamayan bir token asla almaz.