Configuration Scenarios

Your project’s Auth settings determine which sign-in methods are available. This guide shows what options, fields, and example requests/responses you get for each configuration.

Password vs Passwordless

Flow	Password field?	UI example	Use when
Password sign-in	Yes, required	Sign up form: email, password, name. Login: email, password.	Traditional web apps, B2B, forms
Passwordless (OTP)	No	Single screen: email or phone → OTP input → done	Mobile apps, modern SaaS, quick onboarding

Password sign-in: Register (create account) + Login (returning users).
Passwordless: OTP Send + OTP Verify. User never sees a password field.

Quick Reference

Sign-in method	Register	OTP Send	OTP Verify	Custom fields example
Email only	email, password, name	email	email + code	company, role
Phone only	—	phone	phone + code	— (phone is identifier)
Both	email, password, name	email or phone	same + code	phone, company

Configure Sign-in method in Dashboard → Project → Auth.

UI Hints

Password flow (Register + Login):

1. Sign up: form with email, password, name (optional). Call POST /register.
2. Sign in: form with email, password. Call POST /login.
3. Password is required — users must set and remember it.

Passwordless flow (OTP):

1. Single screen: input for email or phone. Call POST /otp/send.
2. Next screen: 6-digit OTP input. Call POST /otp/verify with same identifier + code.
3. No password field — user gets token after verify.

---

Scenario 1: Email Only

Config: Sign-in method = Email OTP only, or Email + Password without phone OTP.

Available:

• POST /auth/register: email, password, name, customFields
• POST /auth/login: email, password
• POST /auth/otp/send (if OTP enabled): email
• POST /auth/otp/verify: email + code

Custom fields: Add company, role (or any keys) in Auth → Custom Registration Fields, then send in customFields.

Example: Register Request

{
  "email": "user@example.com",
  "password": "StrongPassword123!",
  "name": "Jane Doe",
  "customFields": {
    "company": "Acme Inc",
    "role": "Developer"
  }
}

Example: Register Response (200 OK)

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user-uuid-here",
    "email": "user@example.com",
    "name": "Jane Doe"
  },
  "requiresVerification": false
}

Example: GET /me (after login)

{
  "id": "user-uuid",
  "email": "user@example.com",
  "name": "Jane Doe",
  "email_verified_at": null,
  "profile_extras": {
    "company": "Acme Inc",
    "role": "Developer"
  }
}

---

Scenario 2: Phone Only

Config: Sign-in method = Phone OTP only. No email+password register in this flow; users are created on first OTP send when auto-create is enabled.

Available:

• POST /auth/otp/send: phone only
• POST /auth/otp/verify: phone + code
• GET /auth/me: User info after login

Custom fields: None collected at OTP signup. phone is the identifier and stored in the user record.

Example: OTP Send Request

{
  "phone": "+919876543210"
}

Example: OTP Send Response (200 OK)

{
  "message": "OTP sent successfully",
  "accountExists": false
}

Example: OTP Verify Request

{
  "phone": "+919876543210",
  "code": "123456"
}

Example: OTP Verify Response (200 OK)

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user-uuid-here",
    "email": "p9876543210@otp.aerostack.invalid",
    "name": null
  }
}

Note

Phone-only users receive a placeholder email. Use the token for authenticated requests. GET /me returns user info; profile_extras may be empty.

---

Scenario 3: Both (Email and Phone)

Config: Sign-in method = Both (Email or Phone OTP). Register (email+password) is typically also available.

Available:

• POST /auth/register: email, password, name, customFields (e.g. phone, company)
• POST /auth/otp/send: either email or phone
• POST /auth/otp/verify: same identifier + code

Custom fields: Add phone (prebuilt) and company in Auth → Custom Registration Fields to collect during register.

Example: Register Request (with phone + company)

{
  "email": "user@example.com",
  "password": "StrongPassword123!",
  "name": "Jane Doe",
  "customFields": {
    "phone": "+919876543210",
    "company": "Acme Inc"
  }
}

Example: Register Response (200 OK)

Same as Scenario 1. Token and user returned.

Example: OTP Send (phone)

{
  "phone": "+919876543210"
}

Example: OTP Send (email)

{
  "email": "user@example.com"
}

Example: OTP Verify (phone)

{
  "phone": "+919876543210",
  "code": "123456"
}

Example: GET /me (after register with custom fields)

{
  "id": "user-uuid",
  "email": "user@example.com",
  "name": "Jane Doe",
  "email_verified_at": null,
  "profile_extras": {
    "phone": "+919876543210",
    "company": "Acme Inc"
  }
}

---

Related

• POST /auth/register – Full register API reference
• POST /auth/otp/send – OTP send reference
• POST /auth/otp/verify – OTP verify reference
• GET /auth/me – Current user reference