> ## Documentation Index
> Fetch the complete documentation index at: https://orchestrator-docs.hexoforge.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Register user

> Create a new tenant user account.

Creates a new tenant user. Requires `X-API-Key`. Replace `{project_id}` with your project UUID.

## Request body

<ParamField body="email" type="string" required>
  Valid email, max 320 characters.
</ParamField>

<ParamField body="password" type="string" required>
  8–128 characters.
</ParamField>

<ParamField body="name" type="string">
  Display name, max 256 characters.
</ParamField>

<ParamField body="phone" type="string">
  Phone string, max 32 characters.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary JSON metadata.
</ParamField>

## Response

<Tabs>
  <Tab title="201 — verification disabled">
    ```json theme={null}
    {
      "access_token": "eyJhbGciOiJSUzI1NiIs...",
      "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2g...",
      "token_type": "bearer",
      "expires_in": 900,
      "requires_email_verification": false,
      "last_login_method": null
    }
    ```

    <ResponseField name="access_token" type="string">
      JWT access token.
    </ResponseField>

    <ResponseField name="refresh_token" type="string">
      Refresh token (single-use chain).
    </ResponseField>

    <ResponseField name="token_type" type="string">
      Always `bearer`.
    </ResponseField>

    <ResponseField name="expires_in" type="integer">
      Access token lifetime in seconds.
    </ResponseField>

    <ResponseField name="requires_email_verification" type="boolean">
      `false` when email verification is off and tokens are returned.
    </ResponseField>

    <ResponseField name="last_login_method" type="string | null">
      Previous sign-in method for UX hints (`null` on first registration).
    </ResponseField>
  </Tab>

  <Tab title="201 — verification enabled">
    ```json theme={null}
    {
      "access_token": null,
      "refresh_token": null,
      "token_type": "bearer",
      "expires_in": null,
      "requires_email_verification": true,
      "last_login_method": null
    }
    ```

    The user must complete [Verify email](/api-reference/gate/verify-email) before logging in.
  </Tab>
</Tabs>

## Status codes

| Code | Meaning                                                       |
| ---- | ------------------------------------------------------------- |
| 201  | User created                                                  |
| 400  | Password validation failed                                    |
| 403  | Registration disabled, user limit, IP block, or firewall deny |
| 409  | Email already registered                                      |
| 429  | Rate limited                                                  |