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

# Integrate with Supabase

> Securely connect your microapp to Supabase using JWT bridging for authentication and data access.

Integrate your microapp with Supabase by bridging authentication using JWT tokens generated by Microapp. This approach lets you use Microapp for user identity and securely access Supabase data—**without using Supabase's built-in authentication**.

<Tip>
  Supabase authentication is <b>not compatible</b> with Microapp. Always use the JWT token generated by Microapp to authenticate and check users in Supabase.
</Tip>

## Prerequisites

* A [Supabase account](https://supabase.com/) and project
* Your microapp set up with one of our [supported frameworks](/getting-started/supported-frameworks)

## 1. Set Up Your Supabase Project

1. Sign in to [Supabase](https://app.supabase.com/) and create a new project.
2. Note your project's **URL** and **anon/public API key** from the project settings. You'll need these to connect your microapp.

## 2. Install the SDKs

Install both the Microapp SDK and Supabase client:

<CodeGroup>
  ```bash npm theme={null}
  npm install @microapp-io/react @supabase/supabase-js
  ```

  ```bash yarn theme={null}
  yarn add @microapp-io/react @supabase/supabase-js
  ```

  ```bash pnpm theme={null}
  pnpm add @microapp-io/react @supabase/supabase-js
  ```
</CodeGroup>

## 3. Create a Supabase Hook

Create a React hook that provides a Supabase client authenticated with the current user's JWT token:

```ts theme={null}
// src/hooks/useSupabase.ts
import { useMemo } from 'react';
import { useAuth } from '@microapp-io/react';
import { createClient } from '@supabase/supabase-js';

const SUPABASE_URL = 'your-supabase-url';
const SUPABASE_ANON_KEY = 'your-anon-key';

export function useSupabase() {
  const { userJwtToken } = useAuth();

  return useMemo(() => {
    return createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
      global: {
        headers: userJwtToken ? { Authorization: `Bearer ${userJwtToken}` } : {},
      },
      auth: {
        autoRefreshToken: false,
        detectSessionInUrl: false,
        persistSession: false,
      },
    });
  }, [userJwtToken]);
}
```

Replace `your-supabase-url` and `your-anon-key` with your actual Supabase project values.

## 4. Use Supabase in Your Components

Now you can use both Microapp and Supabase authentication in your components:

```tsx theme={null}
// src/pages/Index.tsx
import { useAuth } from '@microapp-io/react';
import { useSupabase } from '@/hooks/useSupabase';

export default function Index() {
  const { isAuthenticated, requestLogin, user } = useAuth();
  const supabase = useSupabase();

  const handleCreateTodo = async () => {
    if (!isAuthenticated) {
      requestLogin();
      return;
    }

    await supabase.from('todos').insert({
      user_id: user.id,
      title: 'My Todo',
    });
  };

  return (
    <button onClick={handleCreateTodo}>
      {isAuthenticated ? 'Create Todo' : 'Log In to Create'}
    </button>
  );
}
```

## 5. Configure JWT Authentication

To let Supabase validate Microapp's JWT tokens, both systems must use the same JWT secret:

1. **Copy the Microapp JWT Secret**

* Go to **Microapp Creator Dashboard → Settings → JWT Secret** and copy the value
* Or generate a new secret if needed

2. **Set the Same Secret in Supabase**

* Go to **Supabase Dashboard → Project Settings → Auth → JWT Settings**
* Paste the same secret under `JWT Secret`

<Tip>
  Both Microapp and Supabase must use the <b>exact same JWT secret</b> so that tokens can be verified.
</Tip>

## 6. Set Up Row Level Security (RLS)

Enable secure access to user-owned data with RLS policies:

```sql theme={null}
-- Enable RLS on your table
ALTER TABLE public.todos ENABLE ROW LEVEL SECURITY;

-- Allow users to view their own todos
CREATE POLICY "Users can view their own todos"
  ON public.todos
  FOR SELECT
  USING (auth.uid() = user_id);

-- Allow users to create their own todos
CREATE POLICY "Users can create their own todos"
  ON public.todos
  FOR INSERT
  WITH CHECK (auth.uid() = user_id);
```

## 7. Deploy and Test

1. Test authentication and database queries in your local environment
2. Ensure your environment variables are set in your deployment platform
3. Deploy your microapp as usual

<Tip>
  For advanced features like real-time subscriptions, storage, and edge functions, see the [Supabase documentation](https://supabase.com/docs).
</Tip>

***

## Understanding JWT Authentication Flow

Here's how authentication works between Microapp and Supabase:

### Data Flow Overview

1. User logs in via Microapp and receives a JWT token
2. Your React app gets the token using `useAuth()`
3. The `useSupabase` hook creates a client with the user's token
4. All Supabase queries are authenticated with that token
5. Supabase enforces Row Level Security using the token's `sub` claim as the user ID

### Token Structure

Microapp JWT tokens include these important claims:

```json theme={null}
{
  "aud": "authenticated",
  "role": "authenticated",
  "metadata": {
    "user": {
      "id": "b07a3a69-852c-496f-9bad-b4bd1a63e61a",
      "email": "user@microapp.io",
      "pictureUrl": null
    },
    "app": {
      "id": "e21e0abf-00fe-4b56-ac19-f6764af38760",
      "slug": "todo-app"
    }
  },
  "sub": "cbe35973-d7d3-4ee7-9ec3-bf76a15dbf9f",
  "iat": 1750941947,
  "exp": 1750945547
}
```

* `sub` is used by Supabase as `auth.uid()` and contains the user ID
* `metadata.user` contains user information like email and profile picture
* `metadata.app` contains the microapp details
* `aud` and `role` are set to "authenticated" for Supabase compatibility
* `exp` is the expiration time (in seconds since epoch)
* `iat` is the issued-at time

### Token Management

* **Default TTL:** Tokens expire after 60 minutes by default
* **Custom TTL:** You can modify the token expiration time in the Microapp Creator Dashboard
* **Token Refresh:** To get a new token, call `getUserJwtToken()` method or refresh the page
* **Automatic Handling:** The `useSupabase` hook automatically uses the latest token from `useAuth()`

### Best Practices

* **JWT Bridging:** Microapp handles authentication and provides a JWT. You pass this token to Supabase for secure data access
* **Token Expiry:** If Supabase returns authentication errors, the token may have expired - simply refresh or call `getUserJwtToken()`
* **Security:** Never share JWT secrets publicly. Use environment variables for all secrets and keys

## Next Steps

* Explore Supabase features: [Auth](https://supabase.com/docs/guides/auth), [Database](https://supabase.com/docs/guides/database), [Storage](https://supabase.com/docs/guides/storage)
* Integrate with Microapp's [Identity](/core-concepts/identity/overview) and [Monetization](/core-concepts/monetization) systems
* [Distribute your microapp](/core-concepts/distribution) on the Microapp marketplace