Auth API reference

Auth API · Consumer-Auth

post/{app_slug}/v1/auth/signupAuth

Sign up an EndUser

Create an EndUser account inside the app and immediately mint a session. The supplied email becomes the primary email contact, unverified at signup. When the app has completed Mail notification setup, a verification code is auto-emailed to the address; customers delivering their own verification messages call /auth/request-verification (or /auth/send-verification-email) instead — doing so invalidates the auto-sent code, so the user only ever has one valid code. Subject to the app-configured signup policy (signup enabled, password policy, default role, optional `signup_requires_pak`). The password must clear the app's length + character-class rules, a common-password deny-list, and — unless the app sets `password_breach_check` to `warn` or `off` — a public breach corpus; a breached password is refused with 400 `PASSWORD_BREACHED` and a deny-listed one with 400 `PASSWORD_TOO_COMMON`. The breach lookup is k-anonymous (only five characters of the password's SHA-1 leave the service) and fails open, so an unreachable corpus never blocks a signup. When the app runs `auth_config.mfa: "required"`, the account is still created but NO session is minted: the response is the `ConsumerMfaEnrollmentRequiredResponseDto` shape (`mfa_enrollment_required: true`), completed via `POST /auth/mfa/enroll` + `/auth/mfa/enroll/verify`. Inside `mfa_grace_days` of account creation — which a fresh signup always is when the window is non-zero — the ordinary token pair is returned with `mfa_enrollment_due_at` set instead. When the app has bot protection on (`auth_config.bot_protection`, Cloudflare Turnstile or hCaptcha), send the widget response as `bot_protection_token`. Auth verifies it with the provider before it looks at the email, username or password, and refuses the sign-up when the token is missing (400 `BOT_PROTECTION_REQUIRED`), rejected (403 `BOT_PROTECTION_FAILED`) or cannot be checked (503 `BOT_PROTECTION_UNAVAILABLE`; no account is created). This applies to PAK-authenticated calls too: a backend forwards the token its browser received.

Path parameters

app_slug*string

Slug of the app.

Request body

username*string

Unique username inside the app. 3-32 characters: letters, numbers, dot, underscore, hyphen. No "@" — a username shaped like an email address would sit in front of that address at sign-in.

Example: "john_doe"

email*string

EndUser email address. Becomes the primary email contact and the default verification target.

Example: "jane@example.com"

password*string

Password. Must satisfy the app-configured policy (default: 12+ chars, at least one uppercase letter and one digit), must not be on the common-password deny-list, and — unless the app sets `password_breach_check` to `off` or `warn` — must not appear in the public breach corpus.

Example: "CorrectHorseBatteryStaple"

display_namestring

Optional display name shown back to the user.

Example: "Jane Doe"

bot_protection_tokenstring

The response token from the app's bot-protection widget (Cloudflare Turnstile or hCaptcha). Required when the app has bot protection switched on (`auth_config.bot_protection.enabled`); ignored otherwise. Auth verifies it with the provider before anything else about the sign-up is looked at. Tokens are single-use and expire after a few minutes, so render a fresh widget for every attempt. A backend that signs users up with a Platform API Key forwards the token its browser received.

Example: "0.Zx3xS9oWnZ1Y…"

Response · 201 Account created. A session was minted unless `mfa_enrollment_required` is present — branch on that flag.

object

Example

Request

POST https://api.auth.productcraft.co/{app_slug}/v1/auth/signup
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "username": "john_doe",
  "email": "jane@example.com",
  "password": "CorrectHorseBatteryStaple",
  "display_name": "Jane Doe",
  "bot_protection_token": "0.Zx3xS9oWnZ1Y…"
}

Response

{}