# Unified User Onboarding

## Unified User Onboarding

**`POST /accounts/push/onboard`**

Registers a new user account and fully sets up their Hedera account, DID, and cryptographic keys in a single async call. Returns a `taskId` immediately — poll `GET /tasks/onboard/{taskId}` for progress.

**Authentication:** Bearer token required for non-demo mode (`Authorization: Bearer <token>`). Only a Standard Registry user may onboard new accounts outside of demo mode.

***

### Request

#### Request Body

```json
{
  "username": "example_user",
  "password": "examplePassword123",
  "password_confirmation": "examplePassword123",
  "role": "USER",
  "parent": "example_registry"
}
```

| Field                   | Type    | Required                 | Description                                                                           |
| ----------------------- | ------- | ------------------------ | ------------------------------------------------------------------------------------- |
| `username`              | string  | Yes                      | Username for the new account                                                          |
| `password`              | string  | Yes                      | Account password                                                                      |
| `password_confirmation` | string  | Yes                      | Must match `password`                                                                 |
| `role`                  | string  | Yes                      | `STANDARD_REGISTRY` or `USER`                                                         |
| `parent`                | string  | Required for `USER` role | Standard Registry username. Links the `USER` account to their registry                |
| `hederaAccountId`       | string  | No                       | Hedera account ID (e.g. `0.0.4532001`). Auto-generated if omitted                     |
| `hederaAccountKey`      | string  | No                       | Hedera account private key (DER encoded). Required when `hederaAccountId` is provided |
| `vcDocument`            | object  | No                       | VC credential subject to publish during setup                                         |
| `didDocument`           | object  | No                       | Custom DID document. Auto-generated if omitted                                        |
| `didKeys`               | array   | No                       | Private keys for the custom DID document methods                                      |
| `useFireblocksSigning`  | boolean | No                       | Use Fireblocks instead of local key signing                                           |
| `fireblocksConfig`      | object  | No                       | Fireblocks configuration. Required when `useFireblocksSigning` is `true`              |

***

### Response

#### Success Response

**Status:** `202 Accepted`

```json
{
  "taskId": "63e3e5e8-a01b-3c00-1234-abcd5678ef90",
  "expectation": 11,
  "action": "Onboard user"
}
```

#### Error Responses

| Status                      | Description                                                                           |
| --------------------------- | ------------------------------------------------------------------------------------- |
| `400 Bad Request`           | Passwords don't match, missing required fields, or `parent` not found for `USER` role |
| `401 Unauthorized`          | Caller is not authenticated (non-demo mode)                                           |
| `403 Forbidden`             | Caller does not have Standard Registry role                                           |
| `409 Conflict`              | Username already exists                                                               |
| `422 Unprocessable Entity`  | `hederaAccountId` provided without `hederaAccountKey`                                 |
| `500 Internal Server Error` | Unexpected server failure                                                             |

***

## Polling Onboarding Task Status

**`GET /tasks/onboard/{taskId}`**

Returns the current status of an onboarding task. No authentication required. Restricted to tasks started by `POST /accounts/push/onboard` — any other task type returns `401 Unauthorized`.

**Authentication:** None

***

### Request

#### Path Parameters

| Parameter | Type   | Required | Description                                       |
| --------- | ------ | -------- | ------------------------------------------------- |
| `taskId`  | string | Yes      | Task ID returned by `POST /accounts/push/onboard` |

***

### Response

#### Success Response

**Status:** `200 OK`

```json
{
  "taskId": "63e3e5e8-a01b-3c00-1234-abcd5678ef90",
  "action": "Onboard user",
  "expectation": 11,
  "completed": false,
  "failed": false,
  "error": null
}
```

| Field       | Description                                                    |
| ----------- | -------------------------------------------------------------- |
| `completed` | `true` when the task has finished successfully                 |
| `failed`    | `true` when the task has failed                                |
| `error`     | Error message object when `failed` is `true`, otherwise `null` |

> Sensitive credentials (`publicKey`, `hederaAccountId`, `did`) are never returned by this endpoint. Once `completed` is `true`, the new user must log in and call `GET /tasks/{taskId}` with their own Bearer token to retrieve their full credentials.

#### Error Responses

| Status                      | Description                               |
| --------------------------- | ----------------------------------------- |
| `401 Unauthorized`          | `taskId` belongs to a non-onboarding task |
| `500 Internal Server Error` | Unexpected server failure                 |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://guardian.hedera.com/guardian-dev/guardian/users/user-operations/account-apis/unified-onboarding.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.