# Kullanıcıları ara

`POST /v1/users:search` · izin `users:read`

Kişisel veri içeren filtrelerle kullanıcıları arar. Bu filtreler yalnızca istek gövdesinde kabul edilir, asla sorgu dizesinde kabul edilmez, çünkü sorgu dizeleri proxy ve istemci günlüklerine düşer. Filtreler VE ile birleşir ve en az bir kimlik filtresi zorunludur. Eşleşmeler tam eşleşmedir; önek ve alt dize araması sunulmaz. Çok fazla kullanıcıyla eşleşen bir arama `search_too_broad` hatasıyla başarısız olur; filtreleri daraltın.

## İstek

Sayfalama parametreleri sorgu dizesinde gönderilir; kişisel veri içermezler.

| Parametre | Konum | Zorunlu | Açıklama |
|---|---|---|---|
| `limit` | query | hayır | Sayfa boyutu, 1 ile 100 arası. Varsayılan 20. |
| `after` | query | hayır | `list_metadata.after` değerinden alınan opak imleç. `before` ile birlikte kullanılamaz. |
| `before` | query | hayır | `list_metadata.before` değerinden alınan opak imleç. `after` ile birlikte kullanılamaz. |
| `order` | query | hayır | Oluşturulma zamanına göre `asc` veya `desc`. Varsayılan `desc`. |

Gövde alanları:

| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
| `email` | string | hayır | Tam e-posta adresi. |
| `phone` | string | hayır | E.164 biçiminde tam telefon numarası. |
| `username` | string | hayır | Tam kullanıcı adı. |
| `email_domain` | string | hayır | Tam e-posta alan adı. |
| `app_metadata`, `user_metadata` | object | hayır | En fazla 3 üst düzey anahtar; her anahtar bir skaler değere eşit olmalıdır. |
| `status` | string | hayır | `active`, `blocked` veya `pending_deletion`. |

İmleç yalnızca üzerinde verildiği filtre ve sıralama kümesiyle geçerlidir.

## Yanıt

`200 OK`. `data` sayfadaki kullanıcıları içerir; `list_metadata.before` ve `list_metadata.after` önceki ve sonraki sayfanın imleçleridir (yoksa `null`). Toplam sayı döndürülmez.

Anahtarda `users:read_pii` izni yoksa kişisel veriler maskelenir: `email` değeri `a***@e***.com` olur, `phone_number` yalnızca son 2 hanesini korur (`+**********67`), `name`, `given_name`, `family_name`, `middle_name` ve `nickname` baş harflere dönüşür (`A. L.`), `username` yalnızca ilk karakterini korur (`a***`), `birthdate` `****-**-**` olur ve `address` `{"redacted": true}` olur. `user_metadata` ve `app_metadata` maskelenmez. `users:read_pii` izni olmayan bir anahtar yine de tam kişisel veri filtreleriyle arama yapabilir; sonuçlar maskelenmiş olur.

```json
{
  "data": [ {
    "id": "usr_0a1b2c3d4e5f6g7h8j9k0m1n2p",
    "kind": "regular",
    "status": "active",
    "external_id": null,
    "username": null,
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "email_verified": true,
    "phone_number": null,
    "phone_verified": false,
    "user_metadata": {},
    "app_metadata": {},
    "created_via": "admin_api",
    "created_at": "2026-01-15T09:30:00Z",
    "updated_at": "2026-01-15T09:30:00Z",
    "last_sign_in_at": null,
    "deletion_requested_at": null,
    "deletion_due_at": null
  } ],
  "list_metadata": { "before": null, "after": "<opaque cursor>" }
}
```

## Hatalar

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

| HTTP | `code` | Ne zaman |
|---|---|---|
| 400 | `unknown_field`, `invalid_cursor` | Gövdede desteklenmeyen bir alan vardır (örneğin önek filtresi) veya imleç isteğe uymaz. |
| 415 | `unsupported_media_type` | `Content-Type` değeri `application/json` değildir. |
| 422 | `validation_failed`, `search_too_broad` | Bir filtre geçersizdir, kimlik filtresi verilmemiştir veya arama çok fazla kullanıcıyla eşleşir. |
| 401 | `unauthenticated` | API anahtarı eksik, geçersiz veya iptal edilmiştir. |
| 403 | `insufficient_permissions` | Anahtarda `users:read` izni yoktur. |
| 429 | `rate_limited` | Hız sınırı aşıldı; `Retry-After` başlığına uyun. |
| 503 | `service_unavailable` | Bir bağımlılık geçici olarak kullanılamıyor; daha sonra yeniden deneyin. |

## Örnek

```bash
curl -X POST "https://api.eu.keenauth.com/v1/users:search?limit=20" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "ada@example.com"}'
```

## Kişisel veriler

Bu uç nokta kişisel veri içerir: son kullanıcı profili. [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.