Add documentation for Funnels authentication steps

docs/tools/funnels/creating-funnels.mdx

@@ -71,6 +71,63 @@ Screen steps are customizable pages built using RevenueCat's Paywall UI builder.
 
 Once added, you can click on the screen node in Interaction mode and switch to Design mode to customize its content.
 
+### Authentication steps
+
+Authentication steps allow you to redirect users to your own authentication system and bring them back to the funnel once they've logged in. This is useful when you need users to authenticate before proceeding to checkout or accessing certain content.
+
+To add an authentication step:
+
+1. Click **Add page** in the left sidebar
+2. Select **Authentication**
+
+#### Setting up the redirect flow
+
+After adding an authentication step, configure where users will be sent to authenticate:
+
+1. Click on the authentication step in the editor
+2. In the right panel, enter your **External authentication URL**
+3. This should be the URL of your authentication page (e.g., `https://auth.example.com/login`)
+
+:::info Query parameters
+If your external authentication URL includes query parameters (e.g., `https://auth.example.com/login?tracking_id=123`), they will be preserved when RevenueCat appends the `redirect_uri` and `state` parameters. This is useful for passing tracking information or other data to your authentication system.
+:::
+
+When a user reaches this authentication step, RevenueCat will redirect them to your external authentication URL with two query parameters:
+
+- `redirect_uri`: The callback URL where you must redirect users after authentication
+- `state`: A token used to tie the session together (you must return this unchanged)
+
+**Example redirect URL your authentication page will receive:**
+
+```
+https://auth.example.com/login?redirect_uri=https%3A%2F%2Fsignup.cat%2Ffunnel%2Fcallback&state=eyJub25jZSI6IjEyMyIsIndvcmtmbG93X2xpbmtfaWQiOi4uLn0=
+```
+
+#### Redirecting back to the funnel
+
+After a user successfully authenticates, your authentication system must redirect back to the `redirect_uri` with two required query parameters:
+
+- `state`: The exact same state value you received (required)
+- `app_user_id`: The authenticated user's ID from your system (required)
+
+**Example callback URL you should redirect to:**
+
+```
+https://signup.cat/funnel/callback?state=eyJub25jZSI6IjEyMyIsIndvcmtmbG93X2xpbmtfaWQiOi4uLn0=&app_user_id=user_12345
+```
+
+:::warning State parameter is required
+You must include the `state` parameter exactly as you received it. Do not modify this value or RevenueCat validation will fail.
+:::
+
+:::info Callback URL
+The `redirect_uri` parameter will always point to `/funnel/callback` on the appropriate domain (`https://signup.cat/funnel/callback` by default, or your custom domain if configured). For security, we recommend allowlisting these callback URLs in your authentication system. You can either use the `redirect_uri` parameter dynamically in your redirect or hard-code the callback URL if you know your domain configuration.
+:::
+
+#### Auto-advance for authenticated users
+
+If a user who is already authenticated reaches an authentication step, they will automatically advance to the next step without being redirected. This prevents unnecessary re-authentication when users navigate back through your funnel.
+
 ### Checkout steps
 
 Checkout steps handle the payment flow. To add a checkout: