Create a new account

POST

/v1/auth/register

curl --request POST \
  --url https://api.aetherpush.com/v1/auth/register \
  --header 'Content-Type: application/json' \
  --data '{ "email": "adrian@aetherpush.com", "password": "correct horse battery staple", "name": "Adrian Moreno" }'

• Production

Registers a new account with email and password. Provisions a new tenant for the account. Sends a verification email; the account cannot log in until the email is verified.

Rate limited to 5 registration attempts per IP per 60 minutes.

When REGISTRATION_ALLOWLIST is set on the server, emails outside that list receive 403 before an account is created.

Request Body^required

Media typeapplication/json

object

email

required

string format: email

password

required

Plain-text password. Server-side strength validation rejects weak passwords with 400 and a ValidationErrorResponse body.

string format: password

>= 12 characters

name

string

<= 255 characters

Example

{
  "email": "adrian@aetherpush.com",
  "password": "correct horse battery staple",
  "name": "Adrian Moreno"
}

Responses

201

Account created. Verification email dispatched (or queued for resend if delivery failed).

Media typeapplication/json

object

message

required

string

accountId

required

string format: uuid

tenantId

required

string format: uuid

emailSent

required

False if the account was created but the verification email could not be dispatched. Clients should prompt the user to request a new verification email via /v1/auth/resend-verification.

boolean

Example

{
  "message": "Account created. Please check your email to verify your account.",
  "accountId": "5b3f1c8a-4d2e-4a7c-9a1b-8e6f3c2d1b0a",
  "tenantId": "7c4a2b1d-3e5f-4b6c-8d7e-9f0a1b2c3d4e",
  "emailSent": true
}

400

Missing fields, a name longer than 255 characters, a value too long for a column, or a weak password.

Media typeapplication/json

One of:

Error

Error

Standard error envelope. code is the stable machine identifier for client branching and i18n. The wording of error is a human-readable fallback and is not part of the contract. Specialized responses keep narrower code enums where clients already branch on them.

object

error

required

Human-readable error message.

string

code

required

Stable machine code. Prefer this over matching on error. The values this API can answer with are listed in the ApiErrorCode schema of the raw document at https://api.aetherpush.com/openapi.yaml. The field stays an open string here so that a release adding a value does not invalidate this response.

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

ValidationError

ValidationError

object

error

required

string

code

required

string

errors

required

Array<object>

>= 1 items

object

field

required

string

message

required

string

code

required

Stable machine code for this field error.

string

requestId

string

Examples

Missing email or password

{
  "error": "Email and password are required.",
  "code": "email_password_required",
  "requestId": "req_abc123"
}

Register name over 255 characters

{
  "error": "Validation failed.",
  "code": "validation_failed",
  "errors": [
    {
      "field": "name",
      "message": "Field is invalid",
      "code": "field_invalid"
    }
  ],
  "requestId": "req_abc123"
}

Weak password failing strength rules

{
  "error": "Validation failed.",
  "code": "validation_failed",
  "errors": [
    {
      "field": "password",
      "message": "Password must be at least 12 characters long.",
      "code": "password_too_short"
    }
  ],
  "requestId": "req_abc123"
}

403

Registration is restricted by REGISTRATION_ALLOWLIST on this environment. The email is outside the configured list.

Media typeapplication/json

Error

Standard error envelope. code is the stable machine identifier for client branching and i18n. The wording of error is a human-readable fallback and is not part of the contract. Specialized responses keep narrower code enums where clients already branch on them.

object

error

required

Human-readable error message.

string

code

required

Stable machine code. Prefer this over matching on error. The values this API can answer with are listed in the ApiErrorCode schema of the raw document at https://api.aetherpush.com/openapi.yaml. The field stays an open string here so that a release adding a value does not invalidate this response.

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

Example

{
  "error": "Registration is restricted on this environment.",
  "code": "registration_restricted",
  "requestId": "req_abc123"
}

409

An account with this email already exists. When that account is scheduled for deletion, the message adds the deletion date (YYYY-MM-DD, UTC) and the way back: sign in and choose Cancel deletion before that date, or the address becomes available once the deletion runs.

Media typeapplication/json

Error

Standard error envelope. code is the stable machine identifier for client branching and i18n. The wording of error is a human-readable fallback and is not part of the contract. Specialized responses keep narrower code enums where clients already branch on them.

object

error

required

Human-readable error message.

string

code

required

Stable machine code. Prefer this over matching on error. The values this API can answer with are listed in the ApiErrorCode schema of the raw document at https://api.aetherpush.com/openapi.yaml. The field stays an open string here so that a release adding a value does not invalidate this response.

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

Example

{
  "error": "An account with this email already exists.",
  "code": "account_email_exists",
  "requestId": "req_abc123"
}

429

Too many registration attempts from this IP.

Media typeapplication/json

RateLimitError

Returned with HTTP 429 when an endpoint-specific rate limit is hit, including the per-tenant management API budget. Not the process-wide address limiter (see GlobalAddressRateLimitErrorResponse). retryAfterSeconds indicates how long the client should wait before retrying, and matches the Retry-After header when that header is set. code names the limit that fired so clients can translate without matching on error.

object

error

required

string

code

required

string

retryAfterSeconds

required

integer

>= 1

requestId

string

Example

{
  "error": "Too many registration attempts. Please try again later.",
  "code": "too_many_registration_attempts",
  "retryAfterSeconds": 3600,
  "requestId": "req_abc123"
}

500

Internal server error.

Media typeapplication/json

Error

Standard error envelope. code is the stable machine identifier for client branching and i18n. The wording of error is a human-readable fallback and is not part of the contract. Specialized responses keep narrower code enums where clients already branch on them.

object

error

required

Human-readable error message.

string

code

required

Stable machine code. Prefer this over matching on error. The values this API can answer with are listed in the ApiErrorCode schema of the raw document at https://api.aetherpush.com/openapi.yaml. The field stays an open string here so that a release adding a value does not invalidate this response.

string

requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string

Example

{
  "error": "The requested resource was not found.",
  "code": "not_found",
  "requestId": "req_abc123"
}