# Federe bir kimliği kullanıcıya bağlayın

`POST /v1/users/{user_id}/identities` · izin `users:write`

Federe bir kimliği (sosyal, SAML veya OIDC bağlantısının harici konusu) kullanıcıya bağlar; böylece kullanıcı bu bağlantıyla giriş yapabilir. `linked_via` her zaman `admin_api` değerindedir. Bağlantı, bu ortamın etkin bir bağlantısı olmalı ve türü `type` ile eşleşmelidir. Aynı kimlik zaten bu veya başka bir kullanıcıya bağlıysa istek `409` ile başarısız olur ve sahibi açıklanmaz. Harici konu kişisel veridir: şifreli olarak saklanır, hiçbir zaman geri döndürülmez ve yönetim denetim kaydı `user.identity_linked` (işlemi yapan: API anahtarı) bunu içermez. İki kullanıcıyı birleştirme (`source_user_id`) kullanılamaz; bilinmeyen bir alan `400 unknown_field` döndürür.

## İstek

| Parametre | Konum | Zorunlu | Açıklama |
|---|---|---|---|
| `user_id` | path | evet | `usr_` öneki taşıyan kullanıcı kimliği. |

| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
| `type` | string | evet | `social`, `saml` veya `oidc`; bağlantıyla eşleşmelidir (sosyal bağlantı için `social`, aynı stratejideki kurumsal bağlantı için `saml`/`oidc`). |
| `connection_id` | string | evet | `conn_` öneki taşıyan bağlantı kimliği. |
| `subject` | string | evet | Kimlik sağlayıcıdaki harici konu (OIDC `sub`, SAML NameID), en fazla 1024 bayt UTF-8. |

## Yanıt

`GET /v1/users/{user_id}/identities` tarafından döndürülen biçimde, yeni kimlikle birlikte `201 Created`.

```json
{
  "id": "idn_0a1b2c3d4e5f6g7h8j9k0m1n2r",
  "type": "oidc",
  "connection_id": "conn_0a1b2c3d4e5f6g7h8j9k0m1n2s",
  "provider": null,
  "linked_via": "admin_api",
  "created_at": "2026-01-15T09:30:00Z"
}
```

## Hatalar

Her hata, kararlı bir `code` içeren bir `application/problem+json` gövdesidir.

| HTTP | `code` | Ne zaman |
|---|---|---|
| 400 | `malformed_request`, `unknown_field` | Gövde geçerli JSON değilse veya bilinmeyen bir alan içeriyorsa. |
| 409 | `conflict` | Kimlik zaten bir kullanıcıya bağlıysa (`errors[]`: `identity_already_linked`) veya kullanıcı kullanıcı başına kimlik sınırına ulaştıysa (`errors[]`: `identity_limit_reached`). |
| 415 | `unsupported_media_type` | Gövde `Content-Type: application/json` olmadan gönderildiyse. |
| 422 | `validation_failed` | Bir alan eksik veya geçersizse (`/type`, `/connection_id`, `/subject`) ya da bağlantı, bu ortamın `type` ile eşleşen etkin bir bağlantısı değilse (`errors[]`: `/connection_id`, `connection_unavailable`). |
| 404 | `not_found` | Kullanıcı bu ortamda yoksa, siliniyorsa veya kimlik biçimi hatalıysa. |
| 401 | `unauthenticated` | API anahtarı eksik, geçersiz veya iptal edilmişse. |
| 403 | `insufficient_permissions` | Anahtarın `users:write` izni yoksa. |
| 429 | `rate_limited` | Hız sınırı aşıldıysa; `Retry-After` değerine uyun. |
| 503 | `service_unavailable` | Bir bağımlılık geçici olarak kullanılamıyorsa; daha sonra yeniden deneyin. |

## Örnek

```bash
curl -X POST https://api.eu.keenauth.com/v1/users/usr_0a1b2c3d4e5f6g7h8j9k0m1n2p/identities \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "oidc", "connection_id": "conn_0a1b2c3d4e5f6g7h8j9k0m1n2s", "subject": "248289761001"}'
```

## Kişisel veriler

Bu uç nokta kişisel veri içerir: bağlı kimlikler. [KeenAuth API'lerinde kişisel veriler](/docs/policies/personal-data) neyin saklandığını, ne kadar süre tutulduğunu ve nasıl silindiğini açıklar. Hiçbir alanda özel nitelikli kişisel verileri (sağlık, biyometrik veriler, din, siyasi görüşler, cinsel yönelim) göndermeyin.