# Search Your Tenant

Find your tenant's users, wallets and operations from one text: an id, a wallet address, a transaction hash, an email, or the start of a username or email. Every role but the end user may search; each kind of record only for a role that reads it.

## Overview

- **Who may call.** Every tenant role but `user`, on its own tenant (`{id}`: your tenant's id; another tenant's id answers `403`, a tenant that does not exist `404` `TENANT_NOT_FOUND`).
- **Each kind for the roles that read it.** `users`: `owner`, `tenantadmin`, `non_signing_admin`, `auditor`, `security_admin`, `security_auditor`. `wallets` and `operations`: `owner`, `tenantadmin`, `non_signing_admin`, `signer`, `approver`, `editor`, `viewer`, `auditor`. A kind asked for that the caller's role does not read is not searched and is listed in `omitted`; asking only for such kinds answers `403` `SEARCH_KIND_FORBIDDEN`.
- `q`: 3–200 characters, trimmed. `kinds`: `users`, `wallets`, `operations`, comma separated (every kind by default). `limit`: at most this many results of each kind, 1–25 (default 10). There is no paging: narrow the text instead.
- `query.kind` says what the text was read as; `searched` lists the kinds actually searched — those asked for, that the text can find and that the role reads.
- **Results.** A user: `id`, `username`, `email`, `role`, `status`. A wallet: `id`, `userId`, `username`, `address`, `chain`, `isTestnet`, `status` (`active` or `deactivated`). An operation: `id`, `type`, `state`, `chain`, `txHash` (the hash that matched, else the operation's first) and `createdAt`. Each also carries `tenantId` and `tenantName`.
- **Limits.** 30 searches per minute per account (`429` beyond: [Rate Limits](https://docs.aureahub.com/docs/rate-limiting.md)). Each search is written to your tenant's audit trail [Coming soon, upon request](https://docs.aureahub.com/docs/feature-availability.md) as `search.performed` — the kinds, what the text was read as and the counts, never the text itself.

## What the Text Finds

| query.kind | The text, and what it finds |
| --- | --- |
| id | A UUID: the user, wallet or operation with that id. |
| evm_address | `0x` and 40 hex characters: the wallets with that address, in any letter case. |
| evm_hash | `0x` and 64 hex characters: the operations with that transaction hash among their hashes. |
| solana_signature | A base58 text of 64–88 characters: the operations with that Solana signature. |
| solana_address | A base58 text of 32–44 characters: the wallets with that address, and the users whose username starts with it. |
| email | A text with `@`: the users whose email starts with it, in any letter case. |
| text | Anything else: the users whose username or email starts with it, in any letter case. |

## Endpoint

### `GET /v1/admin/tenants/{id}/search`

Authentication: bearer token required.

The tenant's users, wallets and operations matching the text, for the kinds the caller's role reads.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes | Your tenant's id |

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `q` | string | yes | 3–200 characters: an id, a wallet address, a transaction hash, an email, or the start of a username or email |
| `kinds` | string | no | `users`, `wallets`, `operations`, comma separated; every kind by default |
| `limit` | integer | no | Results of each kind, 1–25, default 10 |

**Responses**

`200` OK

```json
{
  "query": { "kind": "evm_address" },
  "searched": ["wallets"],
  "omitted": [],
  "users": [],
  "wallets": [
    {
      "id": "7c1e9b24-3f5a-4d8e-9b6c-1a2f3e4d5c6b",
      "tenantId": "3f1c9a52-6d1e-4c1b-9f0a-2a51e1c0b7d4",
      "tenantName": "Acme Wallet",
      "userId": "5d2c1b0a-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
      "username": "maria.rossi",
      "address": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
      "chain": "base",
      "isTestnet": false,
      "status": "active"
    }
  ],
  "operations": []
}
```

`403` No kind

```json
{
  "statusCode": 403,
  "error": "ForbiddenError",
  "message": "Your role reads none of the kinds of record asked for",
  "details": { "code": "SEARCH_KIND_FORBIDDEN", "omitted": ["users"] }
}
```

`429` Too many

```json
{
  "statusCode": 429,
  "error": "Error",
  "message": "Rate limit exceeded, retry in 1 minute"
}
```

**Example request**

```bash
curl "https://api.aureahub.com/v1/admin/tenants/TENANT_ID/search?q=0x8ba1f109551bD432803012645Ac136ddd64DBA72&kinds=wallets,operations" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

---

Web version: https://docs.aureahub.com/#tenant-search