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.

{
  "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

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 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.