From 3c20e896f340d7c681778ba220088bbd9d83e32e Mon Sep 17 00:00:00 2001
From: masnwilliams <43387599+masnwilliams@users.noreply.github.com>
Date: Tue, 12 May 2026 23:47:22 +0000
Subject: [PATCH] document success_url / error_url query params on hosted ui

Mirrors the onSuccess / onError callbacks the React Component already
exposes. Common ask from mobile integrators using the hosted page inside
an in-app browser who need to bounce back into the host app once auth
completes.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 auth/hosted-ui.mdx | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/auth/hosted-ui.mdx b/auth/hosted-ui.mdx
index 1fb150b..3e6d289 100644
--- a/auth/hosted-ui.mdx
+++ b/auth/hosted-ui.mdx
@@ -204,6 +204,44 @@ if state.status == "AUTHENTICATED":
 ```
 </CodeGroup>
 
+## Success / error redirects
+
+To redirect the user back to your app once the flow finishes — for example, to auto-close the auth window inside a mobile in-app browser — append `success_url` and/or `error_url` query params to `hosted_url`. These mirror the `onSuccess` / `onError` callbacks exposed by the [React Component](/auth/react).
+
+- `success_url` — visited when the session reaches `SUCCESS`. The hosted page appends `profile_name` and `domain` as query params.
+- `error_url` — visited when the session reaches `FAILED`, `CANCELED`, or `EXPIRED`. The hosted page appends `code` (when present) and `message` as query params.
+
+Any scheme is accepted, so mobile integrators can pass a custom scheme (`myapp://auth/done`) to bounce back into the host app.
+
+<CodeGroup>
+```typescript TypeScript
+const login = await kernel.auth.connections.login(auth.id);
+
+const url = new URL(login.hosted_url);
+url.searchParams.set("success_url", "https://example.com/connected");
+url.searchParams.set("error_url", "https://example.com/auth-failed");
+
+window.location.href = url.toString();
+```
+
+```python Python
+from urllib.parse import urlencode, urlparse, urlunparse, parse_qsl
+
+login = await kernel.auth.connections.login(auth.id)
+
+parsed = urlparse(login.hosted_url)
+query = dict(parse_qsl(parsed.query))
+query["success_url"] = "https://example.com/connected"
+query["error_url"] = "https://example.com/auth-failed"
+
+redirect_url = urlunparse(parsed._replace(query=urlencode(query)))
+```
+</CodeGroup>
+
+<Warning>
+The hosted page redirects to whatever URL you pass. Only set these from your own trusted backend — never let an end user supply them directly.
+</Warning>
+
 ## Connection Configuration
 
 Connection-level options — custom login URL, SSO/OAuth, custom proxy, session recording, post-login URL, and updates — apply equally to all integration flows and are documented in [Connection Configuration](/auth/configuration).