> ## 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.

# API Connections

> Connect external services to your app with managed or custom API keys.

**API Connections** let you integrate external services into your app—like AI models, payment processors, analytics tools, and more. Bloom can automatically provide and manage API keys for you, or you can bring your own.

## Why API connections matter

Most modern apps rely on external services:

<CardGroup cols={2}>
  <Card title="AI & Machine Learning" icon="brain">
    Connect to services like Google AI, OpenAI, or Anthropic to add smart features—chatbots, content generation, image analysis, etc.
  </Card>

  <Card title="Payments" icon="credit-card">
    Integrate Stripe, PayPal, or other payment processors to accept payments in your app.
  </Card>

  <Card title="Analytics" icon="chart-line">
    Track user behavior and app performance with services like Mixpanel, Segment, or Google Analytics.
  </Card>

  <Card title="Communication" icon="envelope">
    Send emails (SendGrid, Mailgun), SMS messages (Twilio), or push notifications (Firebase).
  </Card>
</CardGroup>

<Info>
  API keys are like passwords that let your app talk to external services securely. Bloom helps you manage them safely.
</Info>

## Auto-provisioned API keys

Bloom can **automatically provide API keys** for popular services, so you can start using them immediately without creating accounts or managing credentials yourself.

### How it works

<Tabs>
  <Tab title="Enabled (Recommended)">
    **When auto-provisioning is ON:**

    <Check>
      Bloom provides API keys automatically for supported services
    </Check>

    <Check>
      Keys are securely managed and rotated by Bloom
    </Check>

    <Check>
      Usage counts against your plan's credits
    </Check>

    <Check>
      No need to create external accounts or manage credentials
    </Check>

    <Check>
      Start using services immediately
    </Check>

    <Tip>
      This is the fastest way to add external services to your app—perfect for development, testing, and most production use cases.
    </Tip>

    **Supported services:**

    * Google AI (Gemini models)
    * Additional services coming soon

    <Note>
      Auto-provisioned keys are shared across your Bloom apps but isolated per project for security.
    </Note>
  </Tab>

  <Tab title="Disabled">
    **When auto-provisioning is OFF:**

    <Check>
      You provide your own API keys for each service
    </Check>

    <Check>
      Full control over API accounts and billing
    </Check>

    <Check>
      Direct access to service dashboards and logs
    </Check>

    <Check>
      Required for services not supported by Bloom provisioning
    </Check>

    <Info>
      You'll need to create accounts with each external service, generate API keys, and add them as environment variables in Bloom.
    </Info>

    **When to disable auto-provisioning:**

    * You need specific API quotas or rate limits
    * You want direct billing from the service provider
    * You're using services not yet supported by Bloom provisioning
    * Your organization requires managing all API credentials directly
  </Tab>
</Tabs>

### Credit usage warning

<Warning>
  **API provisioning disabled - insufficient credits**

  Your Bloom credits have been exhausted. API calls will fail until you upgrade your plan or disable API provisioning.
</Warning>

If you see this warning:

1. **Upgrade your plan** to get more credits (recommended for continued use)
2. **Disable API provisioning** and use your own API keys instead
3. **Purchase credit top-ups** from your billing dashboard

<Card title="View plans and pricing" icon="credit-card" href="/pricing-and-credits">
  Compare plans and see how credits are used
</Card>

## Environment Variables

Environment variables let you securely store API keys, configuration values, and other sensitive information your app needs to function.

### What are environment variables?

Think of environment variables as a secure storage locker for your app's secrets:

* **API keys** from external services
* **Configuration values** like feature flags or URLs
* **Credentials** for databases or third-party services

They're called "environment" variables because they're specific to where your app is running (development vs. production) and kept separate from your code.

<Info>
  Environment variables are **never exposed** in your app's frontend code or shared publicly. They're only accessible from your backend functions.
</Info>

### Managing variables

<Steps>
  <Step title="Click 'Add Variable'" icon="plus">
    Opens a form to create a new environment variable.
  </Step>

  <Step title="Enter variable details">
    * **Name:** What you'll call this variable in your code (e.g., `STRIPE_API_KEY`)
    * **Value:** The actual key or configuration value

    <Tip>
      Use UPPERCASE\_WITH\_UNDERSCORES for variable names—it's a common convention that makes them easy to identify.
    </Tip>
  </Step>

  <Step title="Save the variable">
    The variable is immediately available in your Convex backend functions.
  </Step>

  <Step title="Use it in your code">
    Access the variable in your backend using `process.env.VARIABLE_NAME`

    ```ts theme={null}
    // Example: Using an API key in a Convex function
    const apiKey = process.env.GOOGLE_AI_API_KEY;
    ```
  </Step>
</Steps>

### Variable status indicators

Each variable shows its current status:

<Tabs>
  <Tab title="Provided by Bloom">
    This variable is auto-provisioned by Bloom. The API key is managed automatically and rotated for security.

    **Example:** `Google_AI` when auto-provisioning is enabled

    <Check>
      No manual configuration needed
    </Check>

    <Check>
      Counts against your plan credits
    </Check>
  </Tab>

  <Tab title="In use">
    This variable is actively being used by your app's backend functions.

    <Check>
      Your code is successfully accessing this variable
    </Check>

    <Check>
      The service connection is working
    </Check>
  </Tab>

  <Tab title="Not in use">
    If a variable shows no status badge, it's defined but not currently being used in any backend functions.

    This might mean:

    * You added it but haven't implemented the feature yet
    * The variable name doesn't match what your code is looking for
    * The code using it isn't being called
  </Tab>
</Tabs>

### Actions for variables

<AccordionGroup>
  <Accordion title="Edit variable" icon="pen">
    Click the **edit icon** (pencil) to change a variable's value.

    <Warning>
      Changing a variable value will affect your live app immediately. Make sure you're updating the correct variable!
    </Warning>

    **Common reasons to edit:**

    * Rotating API keys for security
    * Updating configuration values
    * Fixing incorrect credentials
  </Accordion>

  <Accordion title="Delete variable" icon="trash">
    Click the **delete icon** (trash can) to remove a variable.

    <Warning>
      Deleting a variable that's in use will cause errors in your app. Check that no functions depend on it before deleting.
    </Warning>

    **Check logs after deleting** to ensure no functions are trying to access the removed variable.
  </Accordion>

  <Accordion title="Refresh variables" icon="arrows-rotate">
    Click **Refresh** to reload the list of variables and their current status.

    Useful after:

    * Adding variables in the Convex dashboard directly
    * Making changes in another browser tab
    * Troubleshooting variable visibility issues
  </Accordion>
</AccordionGroup>

## Common use cases

<AccordionGroup>
  <Accordion title="Adding a custom AI API key" icon="key">
    If you want to use your own Google AI, OpenAI, or Anthropic API key:

    <Steps>
      <Step title="Disable auto-provisioning">
        Toggle off "Automatically provision API keys" if it's enabled.
      </Step>

      <Step title="Get your API key">
        * For Google AI: [Google AI Studio](https://aistudio.google.com/)
        * For OpenAI: [OpenAI Platform](https://platform.openai.com/)
        * For Anthropic: [Anthropic Console](https://console.anthropic.com/)
      </Step>

      <Step title="Add as environment variable">
        Click "Add Variable" and enter:

        * Name: `GOOGLE_AI_API_KEY` (or appropriate name)
        * Value: Your API key from the provider
      </Step>

      <Step title="Update your code">
        Make sure your backend functions use `process.env.GOOGLE_AI_API_KEY`
      </Step>

      <Step title="Test the connection">
        Use your app's AI features and check [Logs](/logs) for any errors
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Connecting a payment processor" icon="credit-card">
    To add Stripe, PayPal, or another payment service:

    <Steps>
      <Step title="Create an account">
        Sign up with your chosen payment processor (e.g., [Stripe](https://stripe.com))
      </Step>

      <Step title="Get API credentials">
        Find your API keys in the service's dashboard:

        * Stripe: Dashboard → Developers → API keys
        * Look for "Secret key" or "API key"
      </Step>

      <Step title="Add to environment variables">
        * Name: `STRIPE_SECRET_KEY` (or provider-specific name)
        * Value: Your secret API key

        <Warning>
          Never use "publishable" keys in environment variables—only "secret" keys belong in the backend.
        </Warning>
      </Step>

      <Step title="Implement payment logic">
        Use Bloom's agent to help generate payment processing code, or follow the provider's documentation
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Setting up analytics" icon="chart-simple">
    To track user behavior with Mixpanel, Segment, or Google Analytics:

    <Steps>
      <Step title="Create analytics account">
        Sign up with your chosen analytics platform
      </Step>

      <Step title="Get tracking credentials">
        Each platform provides:

        * API key or Write key
        * Project ID or tracking ID
      </Step>

      <Step title="Add as environment variables">
        Example for Mixpanel:

        * `MIXPANEL_TOKEN`: Your project token
        * `MIXPANEL_SECRET`: Your API secret (if using server-side tracking)
      </Step>

      <Step title="Initialize tracking">
        Add tracking calls to your backend functions or frontend code as needed
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Switching from Bloom-managed to custom keys" icon="right-left">
    If you started with auto-provisioned keys but want to use your own:

    <Steps>
      <Step title="Get your own API key">
        Create an account with the service provider and generate an API key
      </Step>

      <Step title="Add the new variable">
        Create an environment variable with your custom key (don't delete the Bloom one yet)
      </Step>

      <Step title="Update your code">
        Change your functions to use the new variable name
      </Step>

      <Step title="Test thoroughly">
        Verify everything works with your custom key before proceeding
      </Step>

      <Step title="Disable auto-provisioning">
        Once confirmed working, toggle off auto-provisioning to stop using Bloom credits
      </Step>

      <Step title="Remove old variable (optional)">
        Delete the Bloom-provided variable if no longer needed
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

## Security best practices

<CardGroup cols={2}>
  <Card title="Never commit keys to code" icon="code-branch">
    Always use environment variables—never hard-code API keys directly in your app's source code.
  </Card>

  <Card title="Rotate keys regularly" icon="rotate">
    Change API keys periodically for security, especially if team members leave or keys are potentially exposed.
  </Card>

  <Card title="Use separate keys per environment" icon="layer-group">
    If exporting code for production, use different API keys for development vs. production deployments.
  </Card>

  <Card title="Monitor usage" icon="chart-line">
    Check provider dashboards regularly for unexpected API usage that might indicate a security issue.
  </Card>
</CardGroup>

<Warning>
  **If you suspect an API key is compromised:**

  1. Immediately delete the variable in Bloom
  2. Revoke the key in the provider's dashboard
  3. Generate a new key and add it as a fresh variable
  4. Check [Logs](/logs) for suspicious activity
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="API calls failing with 'key not valid'" icon="key">
    **Possible causes:**

    * The API key is incorrect or expired
    * The key doesn't have required permissions
    * Auto-provisioning is disabled but no custom key is set
    * Variable name doesn't match what your code expects

    **Solutions:**

    1. Verify the key is correct in the provider's dashboard
    2. Check the variable name matches your code exactly
    3. Enable auto-provisioning if you want Bloom-managed keys
    4. View [Logs](/logs) for the specific error message
  </Accordion>

  <Accordion title="Variable not showing as 'In use'" icon="circle-question">
    If you added a variable but it doesn't show the "In use" badge:

    * Your code might not be calling the function that uses it yet
    * The variable name in your code might not match exactly
    * You might be checking `process.env` incorrectly in your function

    Check [Backend Dashboard Functions](/backend-dashboard) to verify the function is being called.
  </Accordion>

  <Accordion title="Credits depleted" icon="coins">
    If auto-provisioning is disabled due to insufficient credits:

    **Option 1: Upgrade plan**

    * Get more monthly credits
    * Keep using Bloom-managed keys
    * Simplest for ongoing projects

    **Option 2: Use custom keys**

    * Disable auto-provisioning
    * Add your own API keys
    * Direct billing from service providers
  </Accordion>

  <Accordion title="Can't find my variable" icon="magnifying-glass">
    * Click **Refresh** to reload the variable list
    * Check you're in the correct app's settings
    * Verify the variable was saved (you should see a confirmation)
    * Check if it was accidentally deleted
  </Accordion>
</AccordionGroup>

## Learn more

<CardGroup cols={2}>
  <Card title="View Logs" icon="terminal" href="/logs">
    Debug API connection errors and see request details
  </Card>

  <Card title="Backend Dashboard" icon="chart-line" href="/backend-dashboard">
    Monitor function calls that use API connections
  </Card>

  <Card title="Plans & Pricing" icon="credit-card" href="/pricing-and-credits">
    Understand credit usage for auto-provisioned keys
  </Card>

  <Card title="Convex Environment Variables" icon="book" href="https://docs.convex.dev/production/environment-variables">
    Learn more about how Convex handles environment variables
  </Card>
</CardGroup>