# OAuth2 (N'oluyo ile giriş)

Kişileri kendi onaylarıyla sitende ya da uygulamanda N'oluyo hesabıyla giriş yaptır. /oauth2/token ve /oauth2/revoke istekleri application/x-www-form-urlencoded gövde alır ve hataları {error, error_description} olarak döndürür; /oauth2/@me ve /oauth2/@me/guilds ise Authorization: Bearer <access_token> ister.

## Yetki kodunu ya da yenileme token'ını değiştir (`exchangeOAuthToken`)

**`POST https://noluyo.net/api/v1/oauth2/token`** (`POST /oauth2/token`)

Tek kullanımlık yetki kodunu (PKCE code_verifier ile) ya da yenileme token'ını 1 saatlik yeni erişim token'ı ve 30 günlük yenileme token'ı ile değiştirir. En çok 8 KiB boyutunda application/x-www-form-urlencoded gövde alır. Gizli istemciler client_secret değerini formda ya da HTTP Basic ile gönderir; açık istemciler gizli anahtar olmadan client_id ve PKCE gönderir. Hatalar standart OAuth2 {error, error_description} nesnesiyle döner.

- **Kimlik:** Herkese açık (Authorization başlığı gerekmez)

### Gövde alanları

| Alan | Tür | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `grant_type` | `string` | evet | (authorization_code, refresh_token) |
| `client_id` | `string` | - |  |
| `client_secret` | `string` | - |  |
| `code` | `string` | - |  |
| `redirect_uri` | `string` | - |  |
| `code_verifier` | `string` | - |  |
| `refresh_token` | `string` | - |  |

### Örnek çağrılar

```bash
curl -X POST "https://noluyo.net/api/v1/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&client_id=111540000000000000&client_secret=$CLIENT_SECRET&code=$CODE&redirect_uri=https%3A%2F%2Fornek.com%2Fcb&code_verifier=$CODE_VERIFIER"
```

```js
// JavaScript (noluyo-bot)
await bot.rest.exchangeOAuthToken({ grant_type: "authorization_code", client_id: "111540000000000000", client_secret: process.env.CLIENT_SECRET, code: process.env.CODE, redirect_uri: "https://ornek.com/cb", code_verifier: process.env.CODE_VERIFIER });
```

```py
# Python (noluyo_bot)
await bot.rest.exchange_oauth_token({"grant_type": "authorization_code", "client_id": "111540000000000000", "client_secret": os.environ["CLIENT_SECRET"], "code": os.environ["CODE"], "redirect_uri": "https://ornek.com/cb", "code_verifier": os.environ["CODE_VERIFIER"]})
```

### Yanıt (200)

```json
{
  "access_token": "<ACCESS_TOKEN>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "<REFRESH_TOKEN>",
  "scope": "identify email"
}
```

### Hata kodları

- **HTTP 400:** `invalid_request`, `invalid_grant`, `unsupported_grant_type`
- **HTTP 401:** `invalid_client`
- **HTTP 429:** `temporarily_unavailable`
- **HTTP 503:** `temporarily_unavailable`

## Erişim ya da yenileme token'ını iptal et (`revokeOAuthToken`)

**`POST https://noluyo.net/api/v1/oauth2/revoke`** (`POST /oauth2/revoke`)

Verilen erişim ya da yenileme token'ının ait olduğu yetkinin tüm token'larını geçersiz kılar. Bilinmeyen ya da başka uygulamaya ait token'lar da 200 döner.

- **Kimlik:** Herkese açık (Authorization başlığı gerekmez)

### Gövde alanları

| Alan | Tür | Zorunlu | Açıklama |
| --- | --- | --- | --- |
| `token` | `string` | evet |  |
| `client_id` | `string` | - |  |
| `client_secret` | `string` | - |  |

### Örnek çağrılar

```bash
curl -X POST "https://noluyo.net/api/v1/oauth2/revoke" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=111540000000000000&client_secret=$CLIENT_SECRET&token=$ACCESS_TOKEN"
```

```js
// JavaScript (noluyo-bot)
await bot.rest.revokeOAuthToken({ client_id: "111540000000000000", client_secret: process.env.CLIENT_SECRET, token: process.env.ACCESS_TOKEN });
```

```py
# Python (noluyo_bot)
await bot.rest.revoke_oauth_token({"client_id": "111540000000000000", "client_secret": os.environ["CLIENT_SECRET"], "token": os.environ["ACCESS_TOKEN"]})
```

### Yanıt (200)

```json
{}
```

### Hata kodları

- **HTTP 400:** `invalid_request`
- **HTTP 401:** `invalid_client`
- **HTTP 429:** `temporarily_unavailable`
- **HTTP 503:** `temporarily_unavailable`

## Giriş yapan kişinin kimliğini oku (`getOAuthMe`)

**`GET https://noluyo.net/api/v1/oauth2/@me`** (`GET /oauth2/@me`)

Bir OAuth2 erişim token'ı (`identify` kapsamı) için uygulamayı, onaylı kapsamları, token bitiş zamanını ve kişinin kimliğini döndürür. `email` kapsamı da varsa `email` (doğrulanmamışsa null) ve `email_verified` alanları eklenir.

- **Kimlik:** OAuth2 erişim token'ı (`Authorization: Bearer <ACCESS_TOKEN>`)
- **Hız sınırı:** `oauth_read` (30 / 5s)

### Örnek çağrılar

```bash
curl "https://noluyo.net/api/v1/oauth2/@me" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```js
// JavaScript (noluyo-bot)
await bot.rest.getOAuthMe({ accessToken: process.env.ACCESS_TOKEN });
```

```py
# Python (noluyo_bot)
await bot.rest.get_oauth_me(access_token=os.environ["ACCESS_TOKEN"])
```

### Yanıt (200)

```json
{
  "application": {
    "id": "111540000000000000",
    "name": "Örnek Site"
  },
  "scopes": [
    "identify",
    "email"
  ],
  "expires_at": "2026-11-11T13:00:00Z",
  "user": {
    "id": "111400000000000500",
    "username": "deniz",
    "display_name": "Deniz",
    "avatar": "a1b2c3d4",
    "email": "deniz@ornek.com",
    "email_verified": true
  }
}
```

### Hata kodları

- **HTTP 401:** `unauthorized`
- **HTTP 429:** `rate_limited`
- **HTTP 503:** `maintenance`

## Giriş yapan kişinin sunucularını listele (`listOAuthGuilds`)

**`GET https://noluyo.net/api/v1/oauth2/@me/guilds`** (`GET /oauth2/@me/guilds`)

Kişinin üyesi olduğu sunucuları, her birinin sahibi olup olmadığı ve oradaki etkin izin bitleriyle listeler. `guilds` kapsamını ister.

- **Kimlik:** OAuth2 erişim token'ı (`Authorization: Bearer <ACCESS_TOKEN>`)
- **Hız sınırı:** `oauth_read` (30 / 5s)

### Örnek çağrılar

```bash
curl "https://noluyo.net/api/v1/oauth2/@me/guilds" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```js
// JavaScript (noluyo-bot)
await bot.rest.listOAuthGuilds({ accessToken: process.env.ACCESS_TOKEN });
```

```py
# Python (noluyo_bot)
await bot.rest.list_oauth_guilds(access_token=os.environ["ACCESS_TOKEN"])
```

### Yanıt (200)

```json
[
  {
    "id": "111500000000000000",
    "name": "Topluluk",
    "icon": null,
    "owner": true,
    "permissions": "9007199254740991"
  }
]
```

### Hata kodları

- **HTTP 401:** `unauthorized`
- **HTTP 403:** `oauth_scope_required`
- **HTTP 429:** `rate_limited`
- **HTTP 503:** `maintenance`