# Create User

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

## 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 (`user` or `tenantadmin`). This endpoint returns the new user object including a QR code for payment receiving.

> ℹ️ This endpoint requires a valid admin or tenant bearer token. 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 | Role: user (default) or tenantadmin |

**Responses**

`201` Created

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

`409` Conflict

```json
{ "detail": "Username already taken" }
```

## 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