# List Accounts

Your tenant's accounts, newest first: those you created, and each user's default account while it holds a wallet or once it was written to.

## Overview

- Each account as [Get an Account](https://docs.aureahub.com/docs/account-get.md) answers it, with its users and wallets. How accounts work: [Accounts](https://docs.aureahub.com/docs/guide-accounts.md).
- Filters: `tag`, `customerRefId`, `hidden` (`true` or `false`; both when left out) and `userId` — the accounts the user owns or may see, and the user's default account. Page with `limit` (1–200, default 50) and `cursor`, the previous page's `nextCursor` (`null` on the last page).
- For the roles that read the tenant's transactions — `owner`, `tenantadmin`, `non_signing_admin`, `signer`, `approver`, `editor`, `viewer`, `auditor` —, on their own tenant.

## Endpoint

### `GET /v1/accounts`

Authentication: bearer token required.

The tenant's accounts, newest first.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `tag` | string | no | Only accounts with this tag |
| `customerRefId` | string | no | Only the account with this reference |
| `hidden` | boolean | no | Only hidden (`true`) or only visible (`false`) accounts |
| `userId` | string (uuid) | no | Only the accounts this user owns or may see, and the user's default account |
| `cursor` | string (uuid) | no | The previous page's `nextCursor` |
| `limit` | integer | no | 1–200, default 50 |

**Responses**

`200` OK

```json
{
  "accounts": [
    {
      "id": "3b8f2c6e-1d4a-4e9b-8f7c-2a5d6e9b1c40",
      "customerRefId": "cust-00042",
      "name": "Savings, customer 42",
      "tags": ["retail", "eu"],
      "hidden": false,
      "isDefault": false,
      "frozen": false,
      "users": [
        { "userId": "5d2c1b0a-9e8f-4a7b-8c6d-5e4f3a2b1c0d", "access": "owner" }
      ],
      "wallets": [
        {
          "walletId": "7c1e9b24-3f5a-4d8e-9b6c-1a2f3e4d5c6b",
          "chain": "evm",
          "family": "evm",
          "isTestnet": false,
          "address": "0x52908400098527886E0F7030069857D2E4169EE7",
          "keyManagementScheme": "client_side",
          "label": null,
          "isPrimary": false
        }
      ],
      "createdBy": "0d2f6b8a-4c1e-4a93-b7d5-2e9f1c3a8b60",
      "createdAt": "2026-10-07T09:12:40.511Z",
      "updatedAt": "2026-10-07T09:13:02.118Z"
    },
    {
      "id": "9a4e7c21-6b3d-4f58-a1e9-0c7b2d5f8e34",
      "customerRefId": null,
      "name": null,
      "tags": [],
      "hidden": false,
      "isDefault": true,
      "frozen": false,
      "users": [
        { "userId": "9a4e7c21-6b3d-4f58-a1e9-0c7b2d5f8e34", "access": "owner" }
      ],
      "wallets": [
        {
          "walletId": "2e6f9b13-8c4a-4d70-b5e2-1f3a7c9d0b56",
          "chain": "solana",
          "family": "solana",
          "isTestnet": false,
          "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
          "keyManagementScheme": "client_side",
          "label": "Main",
          "isPrimary": true
        }
      ],
      "createdBy": null,
      "createdAt": "2026-09-30T14:02:11.004Z",
      "updatedAt": "2026-09-30T14:02:11.004Z"
    }
  ],
  "nextCursor": null
}
```

`403` Role

```json
{
  "statusCode": 403,
  "error": "ForbiddenError",
  "message": "Tenant admin access required. Your role does not have permission to perform this action."
}
```

**Example request**

```bash
curl "https://api.aureahub.com/v1/accounts?tag=retail&limit=20" \
  -H "Authorization: Bearer $TENANT_ADMIN_TOKEN"
```

---

Web version: https://docs.aureahub.com/#accounts-list