> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newly.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Adding Authentication

> Add user accounts and login to your app

# Adding Authentication

This guide walks you through adding user authentication to your app, allowing users to create accounts, log in, and access their personal data.

## What You'll Build

* Sign up with email and password
* Log in to existing account
* Persistent login sessions
* Protected routes (only accessible when logged in)
* Logout functionality

## Step 1: Add Auth Screens

Start by asking the AI to create the authentication UI:

```
Add authentication to my app:

1. Create a Login screen with:
   - Email input field
   - Password input field
   - "Sign In" button
   - "Don't have an account? Sign up" link at bottom

2. Create a Sign Up screen with:
   - Email input field
   - Password input field
   - Confirm password field
   - "Create Account" button
   - "Already have an account? Sign in" link

Use the app's existing color scheme and design language.
```

## Step 2: Connect to Backend

Now add the backend authentication logic:

```
Connect the auth screens to the backend:

- When signing up:
  - Validate email format
  - Ensure passwords match
  - Create user account
  - Automatically log in after signup
  - Navigate to home screen

- When logging in:
  - Validate credentials
  - Show error if invalid
  - Navigate to home screen on success
  - Keep user logged in across app restarts
```

<Note>
  This creates the necessary API endpoints in Liquid Backend: `/api/auth/register`, `/api/auth/login`, and `/api/auth/me`.
</Note>

## Step 3: Protect Routes

Make certain screens require authentication:

```
Add authentication protection:
- If user is not logged in, show the Login screen
- After logging in, show the Home screen
- The user should not be able to access Home without logging in
- Check auth status when app launches
```

## Step 4: Add Logout

Add a way for users to sign out:

```
Add a logout button in the Settings screen:
- When tapped, show a confirmation: "Are you sure you want to log out?"
- On confirm, clear the session and return to Login screen
- On cancel, stay on Settings
```

## Step 5: Add User Profile

Show user information in the app:

```
Add a Profile screen that shows:
- User's email address
- Account creation date
- "Edit Profile" button (placeholder for now)
- Logout button at the bottom

Navigate to Profile from a user icon in the header.
```

## Testing Your Auth Flow

Test the complete flow:

<Steps>
  <Step title="Sign Up">
    Create a new account with test credentials
  </Step>

  <Step title="Verify Login">
    After signup, you should be on the home screen
  </Step>

  <Step title="Test Persistence">
    Reload the preview - you should still be logged in
  </Step>

  <Step title="Logout">
    Sign out and verify you're back at login
  </Step>

  <Step title="Login Again">
    Log in with your test credentials
  </Step>
</Steps>

## Common Authentication Patterns

### Showing Auth Status

```
Show the user's name in the header when logged in.
If no name is set, show their email instead.
```

### Forgot Password

```
Add a "Forgot Password?" link on the login screen.
When tapped, show a screen where users enter their email
to receive a password reset link.
```

### Social Login

```
Add "Sign in with Google" and "Sign in with Apple" buttons
below the email/password form.
```

<Warning>
  Social login requires additional configuration in Liquid Backend and the respective provider consoles (Google Cloud, Apple Developer).
</Warning>

<Card title="Apple & Google Login with Supabase" icon="fingerprint" href="/guides/supabase-social-login">
  Using Supabase as your backend? Follow the step-by-step walkthrough for Sign in with Apple and Google.
</Card>

## User-Specific Data

Once authentication is set up, associate data with users:

```
Update the tasks feature so each user only sees their own tasks.
When creating a task, automatically associate it with the current user.
When fetching tasks, only return the current user's tasks.
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Validate Input" icon="check">
    Check email format and password strength
  </Card>

  <Card title="Clear Error Messages" icon="message">
    Tell users exactly what went wrong
  </Card>

  <Card title="Loading States" icon="spinner">
    Show loading indicators during auth operations
  </Card>

  <Card title="Secure Storage" icon="lock">
    Auth tokens are stored securely automatically
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Login fails with valid credentials">
    * Check the backend logs for errors
    * Verify the account was created successfully
    * Try creating a new account
  </Accordion>

  <Accordion title="Session not persisting">
    * Tell the AI: "The login session is not persisting across app restarts"
    * Verify secure storage is being used correctly
  </Accordion>

  <Accordion title="Can't access protected screens">
    * Check the auth state logic
    * Verify the auth check runs on app launch
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Connect Database" icon="database" href="/guides/connecting-database">
    Store user-specific data
  </Card>

  <Card title="Add Payments" icon="credit-card" href="/guides/adding-payments">
    Monetize with subscriptions
  </Card>
</CardGroup>