Pesquisar usuários
Busque usuários do Clowk com GET /api/v1/users/search, filtrando por email, nome e datas de criação ou verificação com wildcards, negação e lógica OR.
GET /api/v1/users/search
Pesquisa usuários da instância com uma linguagem de consulta estruturada. Os filtros são tokens separados por espaço e aceitam correspondência exata, wildcards, negação, lógica OR e comparação de intervalos de data.
Requisição
curl "https://myapp.clowk.dev/api/v1/users/search?query=email:*%40gmail.com%20-email:*test*" \
-H "X-Clowk-Secret-Key: sk_live_..."Headers
| Header | Obrigatório | Descrição |
|---|---|---|
X-Clowk-Secret-Key | Sim | A secret key da sua instância |
Parâmetros de query
| Parâmetro | Tipo | Descrição |
|---|---|---|
query | string | Tokens de pesquisa separados por espaço |
Veja a referência completa de operadores de pesquisa para toda a sintaxe aceita.
Sintaxe da consulta
Operadores
| Sintaxe | Comportamento | Exemplo |
|---|---|---|
field:value | Correspondência exata | email:[email protected] |
field:value* | Começa com | email:jane* |
field:*value | Termina com | email:*@gmail.com |
field:*value* | Contém | email:*gmail* |
field>value | Maior que | created_at>2026-01-01 |
field<value | Menor que | created_at<2026-01-01 |
field>=value | Maior ou igual | created_at>=2026-01-01 |
field<=value | Menor ou igual | created_at<=2026-01-01 |
-field:value | Negação (NOT) | -email:*test* |
OR — mesmo campo repetido
Repetir o mesmo campo gera um OR entre os valores:
email:[email protected] email:[email protected]→ retorna usuários com qualquer um dos dois emails.
Campos aceitos
Qualquer coluna da tabela users pode ser usada como filtro. Campos sensíveis como password_digest ficam sempre de fora.
| Campo | Tipo | Notas |
|---|---|---|
email | string | Aceita wildcards |
name | string | Aceita wildcards |
created_at | datetime | Aceita >, <, >=, <= |
updated_at | datetime | Aceita >, <, >=, <= |
email_verified_at | datetime | Filtra pela data de verificação |
Espaços separam tokens. Valores com várias palavras exigem wildcards — use
name:*Doe*em vez dename:Jane Doe.
Exemplos
Email exato:
?query=email:[email protected]Todos os usuários do Gmail:
?query=email:*@gmail.comUsuários com "Silva" no nome:
?query=name:*Silva*Usuários do Gmail ou Yahoo criados depois de janeiro de 2026:
?query=email:*@gmail.com email:*@yahoo.com created_at>2026-01-01Excluir emails de teste/staging:
?query=-email:*test* -email:*staging*Resposta
200 — Sucesso
Retorna um array filtrado. Mesmo formato de Listar usuários.
[
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"resource": "user",
"data": {
"email": "[email protected]",
"name": "Jane Doe",
"avatar_url": "https://lh3.googleusercontent.com/...",
"email_verified": true,
"providers": ["google"],
"created_at": "2026-03-20T10:30:00Z"
}
}
]Retorna um array vazio [] quando nenhum usuário corresponde à consulta.
401 — Não autorizado
{ "error": "Unauthorized" }Uso no SDK
# Ruby — correspondência exata com hash
client.users.search(email: "[email protected]")
# Ruby — query string pura
client.users.search("email:*@gmail.com created_at>2026-01-01")
# Ruby — excluir emails de teste
client.users.search("-email:*test*")// JavaScript — correspondência exata com objeto
await client.users.search({ email: '[email protected]' })
// JavaScript — query string pura
await client.users.search('email:*@gmail.com created_at>2026-01-01')
// JavaScript — excluir emails de teste
await client.users.search('-email:*test*')Buscar usuário
Busque um usuário do Clowk pelo UUID com GET /api/v1/users/:id usando sua secret key: email, nome, avatar, email verificado e providers OAuth.
Excluir usuário
Exclua um usuário e todas as identidades vinculadas de uma instância do Clowk com o endpoint DELETE /api/v1/users/:id, autenticado pela sua secret key.