---
title: "Start Signup"
method: POST
path: "/api/v1/auth/signup"
tags: ["auth"]
---

# Start Signup

`POST /api/v1/auth/signup`

Route a freshly authenticated identity that has no MAIA account.

Rate Limited: 5 requests per minute per IP address.

Authenticated, but exempt from the terms gate — an account this new has
accepted nothing, and the gate would refuse the very request that creates
the account it would gate. Suspension is still enforced.

A POST rather than a side effect on the profile read: this creates an
account and sends mail, which a GET must never do.

The body is optional and its default is a free signup, so the rate limit,
the terms exemption and the domain rules are one route rather than two: a
second paid-only route would be a second surface to gate, and the abuse
gates are exactly what the paid door does not get to skip.

## Request body

- SignupStartRequest — What the signup door being used is asking for. Optional with a free default so a client that posts no body at all — every client before the paid door existed — signs up exactly as it did.
  - `intent` 'free' | 'paid' — What a public signup is asking for. ``PAID`` is what a buyer arriving from the pricing page carries. It is not a funding fact — nothing is charged until checkout, and the workspace opens on the same joining grant a free signup gets — so it decides exactly one thing, and this is the one statement of it that the rest of the codebase points at rather than restates: the workspace records ``WorkspaceOrigin.DIRECT_PAID`` rather than ``SELF_SERVE_DISCOVERY``, which is what routes the account to checkout. It exempts nothing. Signup is unconditional, so there is no admission for a buyer to be exempt from, and every abuse gate binds either way — a verified address, the rate limits and the disposable-domain block. It is therefore not a privilege worth stealing: everything it unlocks is reachable through the free door by anyone the paid door would admit.

## Response `200`

Successful Response

- SignupResponse — Where a signup ended up. ``account_id`` is absent for the two outcomes that create no account — an address that already has one, and one still waiting on its verification link. ``intent`` is the intent the server actually recorded, never the one the client asked for: with the paid door switched off a paid request comes back ``free``, and a client that routes to checkout on its own request rather than on this answer would send the buyer to a checkout the workspace was never admitted for.
  - `status` 'admitted' | 'preparing' | 'verification_required' | 'already_registered', required
  - `account_id` string, uuid, nullable
  - `intent` 'free' | 'paid' — What a public signup is asking for. ``PAID`` is what a buyer arriving from the pricing page carries. It is not a funding fact — nothing is charged until checkout, and the workspace opens on the same joining grant a free signup gets — so it decides exactly one thing, and this is the one statement of it that the rest of the codebase points at rather than restates: the workspace records ``WorkspaceOrigin.DIRECT_PAID`` rather than ``SELF_SERVE_DISCOVERY``, which is what routes the account to checkout. It exempts nothing. Signup is unconditional, so there is no admission for a buyer to be exempt from, and every abuse gate binds either way — a verified address, the rate limits and the disposable-domain block. It is therefore not a privilege worth stealing: everything it unlocks is reachable through the free door by anyone the paid door would admit.

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-23** `7720763f8bf1` — 1 info
  - removed the `waitlisted` enum value from the `status` response property for the response status `200`
- **2026-09-19** `924eeadc29ad` — 3 info
  - added optional request body
  - added the non-success response with the status `422`
  - added the optional property `intent` to the response with the `200` status
- **2026-08-22** `136e4af4d514` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/maia-analytics/apis/maia-api/changes/api/v1/auth/signup/post.md)

---

[API](https://skmtc.dev/maia-analytics/apis/maia-api.md) · [All operations](https://skmtc.dev/maia-analytics/apis/maia-api/llms.txt) · [OpenAPI document](https://skmtc.dev/maia-analytics/apis/maia-api/revisions/7720763f8bf1?raw)