API version: dev

---

# POST /register — Post register

Endpoint used to create a new user account.

**Note**: This endpoint can be disabled via the `register.enabled` configuration option, in which case a
`403 Forbidden` response is returned instead. It should therefore be considered optional.

`password` can be any string; it is hashed internally and no complexity check is performed. Leading/trailing
whitespace is preserved, though discouraged. `uniqueUserIdentifier` must not already be in use by another account,
otherwise a `400 Bad Request` is returned.

## Request

```bash
curl \
  -H 'Content-Type: application/json' \
  -d '{
        "type": "User",
        "password": "1234",
        "uniqueUserIdentifier": "test@example.com"
      }' \
  https://api.example.com/register
```

## Response

### 201 · Created

User account was created successfully.

#### Headers

```http
Access-Control-Allow-Headers: Authorization, Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method
Access-Control-Allow-Methods: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Location
Allow: GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
Cache-Control: no-cache, private
Location: /455a89b9-4ec7-4b02-b023-bcfbcbba9a9f
X-Powered-By: Ember Nexus API
```

[MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/201) · [HTTP.dev](https://http.dev/201)

### 400 · Bad Request

General issues with the user provided request, e.g. missing properties, malformed properties, failing validation logic etc.

#### Body

```json
{
  "type": "https://api.example.com/error/400/missing-property",
  "title": "Missing property",
  "status": 400,
  "detail": "Endpoint requires that the request contains property 'type' to be set to a valid type."
}
```

#### Headers

`Access-Control-Allow-Headers`, `Access-Control-Allow-Methods`, `Access-Control-Allow-Origin`, `Access-Control-Expose-Headers`, `Allow`, `Cache-Control`, `X-Powered-By`. Descriptions and example values are in the Response Header section below.

#### Schema

Same as `Problem` — see the Response Schema section below.

[MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/400) · [HTTP.dev](https://http.dev/400)

### 400 · Bad Request

The unique user identifier is already used by another account.

#### Body

```json
{
  "type": "https://api.example.com/error/400/reserved-identifier",
  "title": "Reserved identifier",
  "status": 400,
  "detail": "The requested identifier 'test@example.com' is reserved and can not be used."
}
```

#### Headers

`Access-Control-Allow-Headers`, `Access-Control-Allow-Methods`, `Access-Control-Allow-Origin`, `Access-Control-Expose-Headers`, `Allow`, `Cache-Control`, `X-Powered-By`. Descriptions and example values are in the Response Header section below.

#### Schema

Same as `Problem` — see the Response Schema section below.

[MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/400) · [HTTP.dev](https://http.dev/400)

### 401 · Unauthorized

The provided token is either invalid or expired.

#### Body

```json
{
  "type": "https://api.example.com/error/401/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authorization for the request failed due to possible problems with the token (incorrect or expired), password (incorrect or changed), the user's unique identifier, or the user's status (e.g., missing, blocked, or deleted)."
}
```

#### Headers

`Access-Control-Allow-Headers`, `Access-Control-Allow-Methods`, `Access-Control-Allow-Origin`, `Access-Control-Expose-Headers`, `Allow`, `Cache-Control`, `X-Powered-By`. Descriptions and example values are in the Response Header section below.

#### Schema

Same as `Problem` — see the Response Schema section below.

[MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/401) · [HTTP.dev](https://http.dev/401)

### 403 · Forbidden

The register endpoint is disabled via server configuration.

#### Body

```json
{
  "type": "https://api.example.com/error/403/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Requested endpoint, element or action is forbidden."
}
```

#### Headers

`Access-Control-Allow-Headers`, `Access-Control-Allow-Methods`, `Access-Control-Allow-Origin`, `Access-Control-Expose-Headers`, `Allow`, `Cache-Control`, `X-Powered-By`. Descriptions and example values are in the Response Header section below.

#### Schema

Same as `Problem` — see the Response Schema section below.

[MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/403) · [HTTP.dev](https://http.dev/403)

## Request Header

### `Authorization` (optional)

Bearer token for user authentication. If omitted, the request is processed as an anonymous user; if provided, the associated user account is used.

[MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Authorization) · [HTTP.dev](https://http.dev/authorization) · [Authentication guide](/guide/authentication.md)

## Request Body (required)

#### Example

```json
{
  "type": "User",
  "password": "1234",
  "uniqueUserIdentifier": "test@example.com",
  "data": {
    "key": "value"
  }
}
```

#### Schema

```json
{
  "type": "object",
  "required": [
    "type",
    "password",
    "uniqueUserIdentifier"
  ],
  "properties": {
    "type": {
      "type": "string",
      "description": "Must be `User`. No other values are currently possible.",
      "enum": [
        "User"
      ],
      "example": "User"
    },
    "password": {
      "type": "string",
      "description": "The plain text password of the new user. Any string is accepted and is hashed internally; no password complexity check is performed. Leading/trailing whitespace is preserved, though discouraged.",
      "example": "1234"
    },
    "uniqueUserIdentifier": {
      "type": "string",
      "description": "Some attribute uniquely identifying a user, normally an email address. The property name used to store it can be configured server-side.",
      "example": "test@example.com"
    },
    "data": {
      "type": "object",
      "description": "Optional, arbitrary properties stored on the new user element.",
      "additionalProperties": true,
      "example": {
        "key": "value"
      }
    }
  }
}
```

## Response Schema

### `Problem`

RFC 7807 Problem Details object.

```json
{
  "$schema": "https://spec.openapis.org/oas/3.0/schema/2021-09-28#/definitions/Schema",
  "type": "object",
  "description": "RFC 7807 Problem Details object.",
  "properties": {
    "type": {
      "type": "string",
      "format": "uri"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer"
    },
    "detail": {
      "type": "string"
    }
  }
}
```

## Response Header

### `Location` (always)

URL of the newly created resource.

Example: `/455a89b9-4ec7-4b02-b023-bcfbcbba9a9f`

[MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Location) · [HTTP.dev](https://http.dev/location)

### Other Headers

#### `Access-Control-Allow-Headers` (always)

Specifies which HTTP headers can be used during a cross-origin request, returned in preflight responses.

Example: `Authorization, Origin, X-Requested-With, Content-Type, Accept, Access-Control-Request-Method`

[MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Allow-Headers) · [HTTP.dev](https://http.dev/access-control-allow-headers)

#### `Access-Control-Allow-Methods` (always)

Indicates which HTTP methods are permitted for cross-origin requests, typically returned in preflight responses.

Example: `GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK`

[MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Allow-Methods) · [HTTP.dev](https://http.dev/access-control-allow-methods)

#### `Access-Control-Allow-Origin` (always)

Specifies which origin(s) may access the resource.

Example: `*`

[MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Allow-Origin) · [HTTP.dev](https://http.dev/access-control-allow-origin)

#### `Access-Control-Expose-Headers` (always)

Lists the response headers that browsers are allowed to access from JavaScript beyond the default restricted set.

Example: `ETag, Location`

[MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Access-Control-Expose-Headers) · [HTTP.dev](https://http.dev/access-control-expose-headers)

#### `Allow` (always)

Lists the HTTP methods supported by the endpoint; returned alongside a `405 Method Not Allowed` response.

Example: `GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK`

[MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Allow) · [HTTP.dev](https://http.dev/allow)

#### `Cache-Control` (always)

Directives controlling caching behavior for the response.

Example: `no-cache, private`

[MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control) · [HTTP.dev](https://http.dev/cache-control)

#### `X-Powered-By` (always)

Identifies the underlying API implementation.

Example: `Ember Nexus API`

[MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Powered-By) · [HTTP.dev](https://http.dev/x-powered-by)

---

Home: [Ember Nexus API docs](/index.md)

Full site map: [llms.txt](/llms.txt)

Previous: [Post search](/api/post-search.md)

Next: [Post change password](/api/post-change-password.md)