---
title: "Register a new user with email and password"
method: POST
path: "/api/v1/auth/register"
tags: ["auth"]
---

# Register a new user with email and password

`POST /api/v1/auth/register`

Creates a new user account and returns an access token, refresh token, and the new
user object. Two registration paths are supported:

- **Team registration**: supply `team_invite` with a valid team invite ID. The new
  user is added to that team immediately upon registration. Returns HTTP 404 if the
  invite is not found.
- **Standard registration**: supply `password`. An `invite_code` may optionally be
  included for invite-gated apps; an invalid code returns HTTP 404.

Exactly one of `team_invite` or `password` must be provided; omitting both returns
HTTP 400. Password registration must be enabled for the app; disabled apps return
HTTP 403. The response status is HTTP 201 on success.

## Request body

- object
  - `alias` string — Display alias (handle) for the new account.
  - `email` string, required — Email address for the new account.
  - `full_name` string — Full name for the new account.
  - `invite_code` string — Invite code for invite-gated registration. Applied only in the standard registration path.
  - `password` string — Password for the new account. Required for standard (non-team-invite) registration.
  - `team_invite` string — Team invite ID. When provided, the user is added to the team on registration.
  - `timezone` string — IANA timezone name for the new account, e.g. `"America/New_York"`.

## Response `200`

Successful response

- AuthTokens — Credential bundle returned after a successful authentication exchange. Contains the access token, refresh token, and the authenticated user.
  - `expires_in` integer, required — Number of seconds until `token` expires. After this period, use `refresh_token` to obtain a new access token.
  - `metadata` object — Optional auxiliary data associated with this authentication event, such as `onboarding_job_id` when the user is completing onboarding. `null` when no extra context is present.
  - `refresh_token` string, required — Long-lived opaque refresh token. Use this to obtain a new access token when `token` expires.
  - `token` string, required — Short-lived JWT access token. Include this value in the `Authorization: Bearer <token>` header for all authenticated API requests.
  - `token_type` string, required — Token scheme. Always `"Bearer"`.
  - `user` User, required — A platform user account. Represents a human or system actor that can own threads, belong to an organization, and interact with the API.
    - `alias` string — Short handle or alias for the user. `null` if not set.
    - `app` string — ID of the app this user (and their access token) is scoped to (`dap_...`). `null` if the user is not scoped to an app.
    - `app_name` string — Display name of the user's app. `null` when the app association was not preloaded by the caller.
    - `email` string — Email address of the user.
    - `id` string, required — User ID (`usr_...`).
    - `is_system_user` boolean — `true` if this account is an internal system user rather than a human. System users are created automatically by the platform.
    - `metadata` object — Arbitrary key-value metadata attached to the user. Defaults to an empty object.
    - `name` string — Full display name of the user. `null` if the user has not set a name.
    - `org` string — ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.
    - `org_name` string — Display name of the user's organization. `null` when the user is not in an org, or when the org association was not preloaded by the caller.
    - `org_role` string — Role of the user within their organization. One of `"admin"`, `"member"`, or `"viewer"`. `null` when the user is not a member of any organization.
    - `sandbox` string — ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.
    - `sandbox_name` string — Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.

## Other responses

- `400` — Missing required parameters
- `403` — Password registration is not enabled for this organization
- `404` — Team invite not found
- `422` — Validation failed

---

[API](https://skmtc.net/archastro/apis/archastro-platform-api.md) · [All operations](https://skmtc.net/archastro/apis/archastro-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/archastro/archastro-platform-api/revisions/a8772b442f86/schema)