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

# Authentication

> Let users sign in to your app securely with OAuth providers.

**Authentication** lets users sign in to your app using accounts they already have—like Google, GitHub, or Apple ID. Bloom handles the complex security setup automatically, so you can add sign-in to your app without writing code or managing credentials yourself.

## Why authentication matters

Authentication is essential for apps that:

* Store user-specific data (profiles, preferences, saved content)
* Need to know who's using the app (personalized experiences)
* Require secure access control (private content, paid features)
* Track user activity or progress over time

<Info>
  With Bloom, authentication is **pre-configured and ready to use**. You don't need to set up servers, manage API credentials, or worry about security best practices—it's all handled automatically.
</Info>

## How authentication works in Bloom

Bloom uses **OAuth**, an industry-standard protocol that lets users sign in using existing accounts from trusted providers (Google, GitHub, Apple, etc.).

When a user signs in:

1. They tap "Sign in with Google" (or another provider) in your app
2. They're redirected to that provider's secure login page
3. They approve giving your app access to basic info (name, email)
4. They're returned to your app, now signed in
5. Your app can now store and retrieve their personal data

<Check>
  Users never share their password with your app—OAuth keeps credentials secure.
</Check>

## Bloom-managed vs. custom credentials

Bloom offers two ways to configure authentication:

<Tabs>
  <Tab title="Bloom-managed (Recommended)">
    **Quick and automatic setup**

    When you enable a provider with Bloom-managed credentials:

    <Check>
      Authentication works instantly—no configuration needed
    </Check>

    <Check>
      Bloom handles all API keys and security automatically
    </Check>

    <Check>
      Updates and maintenance are managed for you
    </Check>

    <Check>
      Perfect for development, testing, and most production apps
    </Check>

    <Info>
      **Google** comes with Bloom-managed credentials by default. Just toggle it on and users can sign in immediately.
    </Info>

    **When to use Bloom-managed:**

    * You're building an MVP or testing your app
    * You want the fastest setup possible
    * You don't need custom branding on the OAuth consent screen
    * You're comfortable with Bloom managing your auth infrastructure
  </Tab>

  <Tab title="Custom credentials">
    **Advanced control with your own OAuth apps**

    You can use your own OAuth credentials for any provider:

    <Check>
      Full control over OAuth app settings
    </Check>

    <Check>
      Custom branding on consent screens
    </Check>

    <Check>
      Direct access to provider dashboards
    </Check>

    <Check>
      Required for some App Store submissions
    </Check>

    <Warning>
      Custom credentials require creating OAuth applications with each provider (Google Cloud Console, GitHub Developer Settings, Apple Developer Portal, etc.)
    </Warning>

    **When to use custom credentials:**

    * You're publishing to app stores and need your own developer accounts
    * You want custom branding on sign-in screens
    * You need specific OAuth scopes or permissions
    * Your organization requires managing all credentials directly
  </Tab>
</Tabs>

### Available providers

<AccordionGroup>
  <Accordion title="Google" defaultOpen icon="google">
    **Status:** Bloom-managed by default (ready to use immediately) Google authentication is pre-configured with Bloom-managed credentials. The toggle is **on by default**, meaning users can sign in with Google accounts right away.

    **To use Bloom-managed Google auth:**

    * The toggle stays **on** (green)
    * No additional configuration needed
    * Works immediately in your app

    **To use your own Google OAuth:**

    1. Create a project in [Google Cloud
       Console](https://console.cloud.google.com)
    2. Enable the Google+ API
    3. Create OAuth 2.0 credentials
    4. Add your Authorized Origin to allowed origins
    5. Toggle off Bloom-managed and add your credentials in Bloom

    <Card title="Google OAuth Setup Guide" icon="book" href="https://developers.google.com/identity/protocols/oauth2">
      Learn how to create Google OAuth credentials
    </Card>
  </Accordion>

  <Accordion title="GitHub" icon="github">
    **Status:** Not configured by default GitHub authentication requires setup before it can be used.

    **To add GitHub authentication:**

    <Steps>
      <Step title="Click 'Add with agent'">
        This opens a prompt where you can ask Bloom's AI to set up GitHub OAuth for you.
      </Step>

      <Step title="Describe what you need">
        Example: "Add GitHub OAuth so users can sign in with their GitHub accounts"
      </Step>

      <Step title="Follow the setup instructions">
        Bloom will guide you through:

        * Creating a GitHub OAuth App
        * Configuring credentials
        * Testing the integration
      </Step>
    </Steps>

    <Info>
      GitHub OAuth requires creating an OAuth App in [GitHub Developer
      Settings](https://github.com/settings/developers). You'll need your Authorized Origin URL from Bloom.
    </Info>
  </Accordion>

  <Accordion title="Apple" icon="apple">
    **Status:** Not configured by default Apple Sign-In is required if you publish to the iOS App Store and offer other social login options.

    **To add Apple authentication:**

    <Steps>
      <Step title="Click 'Add with agent'">
        Bloom's AI assistant will help configure Apple Sign-In.
      </Step>

      <Step title="Enroll in Apple Developer Program">
        Apple Sign-In requires an [Apple Developer
        Account](https://developer.apple.com/programs/) (\$99/year).
      </Step>

      <Step title="Create a Sign in with Apple service">
        Configure the service in [Apple Developer
        Console](https://developer.apple.com/account).
      </Step>

      <Step title="Add credentials to Bloom">
        Follow Bloom's prompts to enter your Apple Service ID and Key.
      </Step>
    </Steps>

    <Warning>
      **App Store requirement:** If your iOS app offers Google or GitHub login, Apple requires you to also offer "Sign in with Apple" as an option.
    </Warning>

    <Card title="Apple Sign-In Documentation" icon="book" href="https://developer.apple.com/sign-in-with-apple/">
      Learn about Sign in with Apple requirements
    </Card>
  </Accordion>
</AccordionGroup>

## Testing authentication

After configuring providers, test that sign-in works:

<Steps>
  <Step title="Open your app preview">
    Use Bloom's Live Preview or share your app to a test device.
  </Step>

  <Step title="Try signing in">
    Tap each configured provider's sign-in button in your app.
  </Step>

  <Step title="Verify the flow">
    * You should be redirected to the provider's login page
    * After approving, you should return to your app signed in
    * Your app should have access to your basic profile info
  </Step>

  <Step title="Check logs if issues occur">
    If sign-in fails, check [Logs](/logs) for authentication errors. Common issues:

    * Incorrect Authorized Origin
    * Missing OAuth credentials
    * Provider-specific configuration errors
  </Step>
</Steps>

## Switching between Bloom-managed and custom

You can switch authentication modes anytime:

<Tabs>
  <Tab title="From Bloom-managed to custom">
    1. Toggle **off** the Bloom-managed switch for the provider
    2. Click to add your own OAuth credentials
    3. Paste your Client ID and Client Secret from the provider
    4. Save and test the integration

    <Info>
      Your app will continue working during the switch—authentication doesn't go down.
    </Info>
  </Tab>

  <Tab title="From custom to Bloom-managed">
    1. Toggle **on** the Bloom-managed switch for the provider
    2. Bloom automatically takes over credential management
    3. Test that authentication still works

    <Warning>
      Only available for providers that offer Bloom-managed credentials (currently Google).
    </Warning>
  </Tab>
</Tabs>

## Common authentication questions

<AccordionGroup>
  <Accordion title="Do I need all providers configured?">
    No! You only need to configure the providers you want your users to be able to use. Most apps start with just Google (which is pre-configured).
  </Accordion>

  <Accordion title="Can I add more providers later?">
    Yes. Start with one provider and add more anytime. Users who signed in with existing providers won't be affected.
  </Accordion>

  <Accordion title="What if I want password authentication?">
    Bloom currently focuses on OAuth providers because they're more secure and easier to maintain. If you need password auth, reach out to support or use custom authentication after exporting your code.
  </Accordion>

  <Accordion title="Will authentication work in production?">
    Yes! Bloom-managed credentials work in production apps. If you're publishing to app stores, you may want to switch to custom credentials for full control and branding.
  </Accordion>

  <Accordion title="What happens if auth fails?">
    Authentication errors appear in [Logs](/logs) with detailed messages. Common issues:

    * Authorized Origin mismatch
    * Invalid or expired credentials
    * User denied permission

    Check logs for specific error messages and solutions.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<CardGroup cols={2}>
  <Card title="Authorization failed" icon="triangle-exclamation">
    **Check:**

    * Authorized Origin is correctly configured in provider dashboard
    * OAuth credentials are valid and not expired
    * Provider's OAuth app is enabled and approved
  </Card>

  <Card title="Redirect loop" icon="arrows-rotate">
    **Check:**

    * Redirect URI matches your Authorized Origin exactly
    * No trailing slashes or protocol mismatches
    * OAuth app settings saved correctly
  </Card>

  <Card title="User info not available" icon="user-slash">
    **Check:**

    * Required OAuth scopes are enabled (email, profile)
    * User approved data sharing during sign-in
    * Provider account has necessary information filled out
  </Card>

  <Card title="Bloom-managed not working" icon="server">
    **Check:**

    * Toggle is enabled (green)
    * Click **Refresh** to reload provider status
    * Check [Logs](/logs) for system errors
  </Card>
</CardGroup>

<Card title="Still having issues?" icon="life-ring">
  Check [Logs](/logs) for detailed error messages or contact Bloom support with your authentication configuration.
</Card>

## What's next?

<CardGroup cols={2}>
  <Card title="API Connections" icon="plug" href="/api-connections">
    Connect external services and APIs to your app
  </Card>

  <Card title="View Logs" icon="terminal" href="/logs">
    Monitor authentication attempts and debug issues
  </Card>

  <Card title="Backend Dashboard" icon="chart-line" href="/backend-dashboard">
    See user data and authentication metrics
  </Card>

  <Card title="Deploy your app" icon="rocket" href="/deploying-your-app">
    Share your app with users or publish to app stores
  </Card>
</CardGroup>