# Create User

Programmatically create a new user from your server — distinct from the self-registration flow.

> ℹ️ **Your tenant's quorum, where Aurea enables it for your tenant** (a tenant on the institutional security profile by its profile): this call answers `202` `{ "state": "awaiting_quorum", "requestId" }` — the **202** tab below — and nothing is done until another administrator of your tenant approves it; the answer it would have given is then read once by who asked ([Read the Answer](https://docs.aureahub.com/docs/quorum-request-result.md)). With no other administrator able to approve it, it is done at once. [Your Tenant's Quorum](https://docs.aureahub.com/docs/guide-tenant-quorum.md). Every other tenant gets the answers below, unchanged.

## Overview

While `POST /v1/auth/register` is for end-user self-signup (no token required), this endpoint creates a user from your authenticated backend — for example, when provisioning accounts in bulk, migrating users from another system, or creating managed accounts on behalf of your customers.

You can assign a `role` at creation time — any tenant role within your own (see [Roles](https://docs.aureahub.com/docs/authentication.md)); `user` when you send none. The user belongs to your token's tenant. This endpoint returns the new user object including a QR code for payment receiving.

- A role your own does not cover answers `403` `Cannot assign a role that holds permissions your role does not`; `owner` answers `403` `Only an Aurea administrator can name an owner`.
- A username or an email another active user of your tenant already has answers `409` (`Username already exists`, `Email already exists`), with the field in `details`.

> ℹ️ This endpoint requires the bearer token of a role that manages the tenant's users: `owner`, `tenantadmin` or `non_signing_admin`. It is intended for server-to-server calls, not for client-facing sign-up forms.

### `POST /v1/users/`

Authentication: bearer token required.

Programmatically creates a new user from an authenticated server context.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `username` | string | yes | Unique username (3–100 chars, alphanumeric / _ / -) |
| `password` | string | yes | Minimum 8 characters |
| `email` | string | no | Optional email address |
| `role` | string | no | `user` (default), `tenantadmin`, `owner`, `non_signing_admin`, `signer`, `approver`, `editor`, `viewer`, `auditor`, `security_admin` or `security_auditor` — within your own role |

**Responses**

`201` Created

```json
{
  "id": "uuid",
  "username": "bob",
  "email": "bob@example.com",
  "role": "user",
  "status": "active",
  "qrCode": "data:image/png;base64,..."
}
```

`202` Awaiting quorum

```json
{
  "state": "awaiting_quorum",
  "requestId": "4e2b9c17-8a3d-4f60-b5e1-7c9d0a2f6b38"
}
```

`403` Role Above Yours

```json
{
  "statusCode": 403,
  "error": "ForbiddenError",
  "message": "Cannot assign a role that holds permissions your role does not"
}
```

`409` Conflict

```json
{
  "error": "ConflictError",
  "message": "Username already exists",
  "details": { "field": "username", "value": "bob" }
}
```

## Implementation

```javascript
// Server-side: provision a user account programmatically
async function provisionUser(adminToken, { username, email, password, role = 'user' }) {
  const res = await fetch('https://api.aureahub.com/v1/users/', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${adminToken}`
    },
    body: JSON.stringify({ username, email, password, role })
  });

  if (res.status === 409) throw new Error('Username already taken');
  if (!res.ok) throw new Error('Failed to create user');

  return res.json(); // { id, username, email, role, qrCode, ... }
}

// Bulk provision example:
async function importUsers(adminToken, userList) {
  const results = [];
  for (const user of userList) {
    try {
      const created = await provisionUser(adminToken, user);
      results.push({ success: true, id: created.id, username: user.username });
    } catch (err) {
      results.push({ success: false, username: user.username, error: err.message });
    }
  }
  return results;
}
```

---

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