Auth API

POST /auth/signup

Create a new user account.

Auth required: No

Request body:

{
  "email": "user@example.com",
  "password": "securepass123",
  "password_confirmation": "securepass123",
  "name": "Jane Doe"
}

Response (201):

{
  "user": {
    "id": 1,
    "email": "user@example.com",
    "name": "Jane Doe",
    "subscription_tier": "free",
    "subscription_expires_at": null,
    "voice_enabled": false,
    "created_at": "2026-05-26T10:00:00Z",
    "total_points": 0,
    "level_number": 1,
    "level_name": "seedling",
    "level_icon": "🌱",
    "points_to_next_level": 10,
    "next_level_name": "sprout",
    "next_level_points": 10,
    "family_visibility": false,
    "household": null
  },
  "token": "eyJhbGciOi...",
  "refresh_token": "eyJhbGciOi..."
}

Errors:

Status	Cause
422	Validation failed (duplicate email, short password)

curl -X POST http://localhost:3000/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"securepass123","password_confirmation":"securepass123","name":"Jane Doe"}'

---

POST /auth/login

Authenticate with email and password.

Auth required: No

Request body:

{
  "email": "user@example.com",
  "password": "securepass123"
}

Response (200):

Same format as signup response.

Errors:

Status	Cause
401	Invalid email or password

curl -X POST http://localhost:3000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"securepass123"}'

---

POST /auth/refresh

Exchange a refresh token for a new access token.

Auth required: No

Request body:

{
  "refresh_token": "eyJhbGciOi..."
}

Response (200):

{
  "token": "eyJhbGciOi..."
}

Errors:

Status	Cause
400	Refresh token not provided
401	Invalid or expired refresh token

curl -X POST http://localhost:3000/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"eyJhbGciOi..."}'

---

GET /auth/me

Get the current user's profile. Used on app launch to validate the session.

Auth required: Yes

Response (200):

{
  "user": {
    "id": 1,
    "email": "user@example.com",
    "name": "Jane Doe",
    "subscription_tier": "pro",
    "subscription_expires_at": "2027-05-26T00:00:00Z",
    "voice_enabled": true,
    "created_at": "2026-05-26T10:00:00Z",
    "total_points": 85,
    "level_number": 4,
    "level_name": "growing",
    "level_icon": "🌲",
    "points_to_next_level": 65,
    "next_level_name": "rooted",
    "next_level_points": 150,
    "family_visibility": true,
    "household": {
      "id": 1,
      "name": "The Does",
      "is_owner": true
    }
  }
}

curl http://localhost:3000/api/v1/auth/me \
  -H "Authorization: Bearer <access_token>"

---

PATCH /auth/settings

Update user settings (name, email, family visibility, password).

Auth required: Yes

Request body:

{
  "name": "Jane Smith",
  "family_visibility": true
}

To change password, include current_password and password:

{
  "current_password": "oldpass123",
  "password": "newpass456"
}

Response (200):

{
  "user": { ... }
}

Errors:

Status	Cause
422	Current password incorrect, or validation failed

curl -X PATCH http://localhost:3000/api/v1/auth/settings \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Smith","family_visibility":true}'

---

POST /auth/forgot_password

Request a password reset email.

Auth required: No

Request body:

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

Response (200):

{
  "message": "If an account exists with that email, you will receive password reset instructions."
}

TIP

Always returns 200 regardless of whether the email exists, to prevent email enumeration.

curl -X POST http://localhost:3000/api/v1/auth/forgot_password \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com"}'

---

POST /auth/reset_password

Reset password using the token from the email deep link.

Auth required: No

Request body:

{
  "token": "reset_token_from_email",
  "password": "newpass456",
  "password_confirmation": "newpass456"
}

Response (200):

{
  "message": "Password has been reset successfully",
  "token": "eyJhbGciOi...",
  "refresh_token": "eyJhbGciOi..."
}

Errors:

Status	Cause
400	Token or password missing
422	Invalid/expired token, or password validation failed

curl -X POST http://localhost:3000/api/v1/auth/reset_password \
  -H "Content-Type: application/json" \
  -d '{"token":"abc123","password":"newpass456","password_confirmation":"newpass456"}'