Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/eggarcia98/auth-backend/llms.txt

Use this file to discover all available pages before exploring further.

Email/password authentication is the traditional flow: a user registers with an email and password, confirms their email, and signs in to receive HTTP-only session cookies.

​
Signup flow

1

Submit signup request

The client sends a POST /api/v1/auth/signup request with a valid email and a password that meets all requirements.
2

Validate input

The server runs Zod validation against the request body. If any field fails, a 400 error is returned before touching Supabase.
3

Create user in Supabase

supabase.auth.signUp() is called with the email, password, and a emailRedirectTo pointing to FRONTEND_URL/auth/callback.
4

Email confirmation

When email confirmation is enabled in your Supabase project, Supabase sends a confirmation email and returns session: null. The API responds with 201 and a user object but no tokens.When email confirmation is disabled, a full session is returned immediately and tokens are included in the response.

​
Password requirements

Passwords are validated by signupSchema in src/schemas/auth.schemas.ts. All four rules must pass:
RuleRequirement
Minimum lengthAt least 8 characters
Uppercase letterAt least one A–Z character
Lowercase letterAt least one a–z character
NumberAt least one 0–9 digit
The login endpoint uses a less strict schema (min(8) only). The strong requirements above apply only to signup and password reset.

​
Signup request

curl
curl -X POST https://your-domain.com/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "Secur3Pass"}'

​
Signup response — email confirmation required

{
  "success": true,
  "data": {
    "user": {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "email": "user@example.com",
      "emailVerified": false,
      "provider": "email",
      "createdAt": "2024-01-15T10:00:00.000Z",
      "updatedAt": "2024-01-15T10:00:00.000Z"
    },
    "tokens": {
      "accessToken": null,
      "refreshToken": null,
      "expiresIn": null
    }
  },
  "message": "User registered successfully"
}
When email confirmation is required, tokens fields will be null. The user must click the confirmation link in their email before they can log in.

​
Signup response — email confirmation disabled

{
  "success": true,
  "data": {
    "user": {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "email": "user@example.com",
      "emailVerified": true,
      "provider": "email",
      "createdAt": "2024-01-15T10:00:00.000Z",
      "updatedAt": "2024-01-15T10:00:00.000Z"
    },
    "tokens": {
      "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
      "expiresIn": 3600
    }
  },
  "message": "User registered successfully"
}

​
Login flow

1

Submit login request

The client sends a POST /api/v1/auth/login request with email and password.
2

Authenticate with Supabase

supabase.auth.signInWithPassword() is called. If the credentials are wrong or the user does not exist, Supabase returns an error.
3

Tokens written to cookies

On success the controller writes two HTTP-only cookies:
  • accessToken — expires based on expiresIn returned by Supabase (typically 1 hour)
  • refreshToken — expires in 7 days
Both cookies are set with httpOnly: true, sameSite: strict, and secure: true in production.
4

Response returned

The response body confirms success. Tokens are intentionally not included in the body — they live in cookies only.

​
Login request

curl
curl -X POST https://your-domain.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email": "user@example.com", "password": "Secur3Pass"}'

​
Login response

{
  "success": true,
  "message": "Login successful, tokens set in cookies"
}
Pass -c cookies.txt (curl) or credentials: 'include' (fetch) so your client stores and sends the session cookies on subsequent requests.

​
Error cases

ScenarioHTTP statusError message
Invalid email format400Invalid email address
Password too short400Password must be at least 8 characters
Password missing uppercase400Password must contain at least one uppercase letter
Password missing lowercase400Password must contain at least one lowercase letter
Password missing number400Password must contain at least one number
Email already registered409Email already registered
Wrong credentials401Invalid email or password
Email not confirmed401Invalid email or password

​
Error response format

{
  "success": false,
  "error": {
    "message": "Invalid email or password",
    "code": "UNAUTHORIZED"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us