# Create an Account

An account of your tenant, with your reference for the customer, a name, tags and its users. It holds no wallet yet.

## Overview

- Every field is optional. `customerRefId`: 1 to 128 of `A–Z a–z 0–9 _ . : @ / + -`, starting with a letter or a digit; unique in your tenant, and never changed once set. `name`: 1 to 100 characters, no space at either end. `tags`: up to 20, each 1 to 50 of `A–Z a–z 0–9 _ . : -` starting with a letter or a digit, each named once. `hidden`: left out of the default account lists of your own tools (default `false`); nothing else changes.
- `users`: up to 50 of your tenant's users, each named once — `access` `owner` (at most one: the user whose wallets the account will hold; it needs one to hold a wallet) or `viewer`.
- `201` with the account. Refusals: `409` `ACCOUNT_REF_TAKEN` (`Another account of the tenant holds this customerRefId.`, `details.accountId` naming it); `400` `ACCOUNT_USER_UNKNOWN` (`Not a user of this tenant.`, `details.userIds`) for a user that is not your tenant's, or was deleted; `400` `ACCOUNT_REQUEST_INVALID` for a request written wrong ([Accounts](https://docs.aureahub.com/docs/guide-accounts.md)).
- For `owner`, `tenantadmin` and `non_signing_admin`, on their own tenant. With `account.created` to the endpoints that name it.

## Endpoint

### `POST /v1/accounts`

Authentication: bearer token required.

Creates an account of the tenant.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `customerRefId` | string \| null | no | Your reference for the customer; unique, set once |
| `name` | string \| null | no | 1–100 characters |
| `tags` | string[] | no | Up to 20, each named once |
| `hidden` | boolean | no | Default `false` |
| `users` | object[] | no | `[{ userId, access }]`, `access` `owner` (at most one) or `viewer` |

**Responses**

`201` Created

```json
{
  "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": [],
  "createdBy": "0d2f6b8a-4c1e-4a93-b7d5-2e9f1c3a8b60",
  "createdAt": "2026-10-07T09:12:40.511Z",
  "updatedAt": "2026-10-07T09:12:40.511Z"
}
```

`409` Reference taken

```json
{
  "statusCode": 409,
  "error": "ConflictError",
  "message": "Another account of the tenant holds this customerRefId.",
  "details": { "code": "ACCOUNT_REF_TAKEN", "accountId": "3b8f2c6e-1d4a-4e9b-8f7c-2a5d6e9b1c40" }
}
```

`400` Unknown user

```json
{
  "statusCode": 400,
  "error": "BadRequestError",
  "message": "Not a user of this tenant.",
  "details": { "code": "ACCOUNT_USER_UNKNOWN", "userIds": ["e4b1c7d9-2f6a-4c83-9b0e-5a7d3f1c8e26"] }
}
```

**Example request**

```bash
curl -X POST https://api.aureahub.com/v1/accounts \
  -H "Authorization: Bearer $TENANT_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customerRefId": "cust-00042",
    "name": "Savings, customer 42",
    "tags": ["retail", "eu"],
    "users": [{ "userId": "5d2c1b0a-9e8f-4a7b-8c6d-5e4f3a2b1c0d", "access": "owner" }]
  }'
```

---

Web version: https://docs.aureahub.com/#account-create