Redirects

Banata Auth uses redirect configuration to control where users are sent during authentication flows — after sign-in, sign-out, email verification, password reset, and Admin Portal operations. All redirect URIs are stored in the backend and managed through the dashboard.

How Redirects Work

1. User triggers an auth flow (sign-in, sign-out, password reset, etc.)
2. Banata Auth checks the redirect configuration for the relevant URI
3. User is redirected to the configured URL after the flow completes
4. If no redirect is configured, the flow uses sensible defaults

Redirect configuration is stored as a single JSON document in the backend. This makes it easy to update multiple redirect URIs atomically and ensures consistency across all auth flows.

Redirect Settings

Application Redirects

Admin Portal Redirects

Redirect Data Model

The entire redirect configuration is stored as a flat key-value map:

type RedirectsData = Record<string, string | string[]>;

Single-value fields store a string. Multi-value fields (Redirect URIs, Sign-out redirects) store a string[].

Example:

{
  "redirectUris": ["https://myapp.com/callback", "https://staging.myapp.com/callback"],
  "appHomepage": "https://myapp.com",
  "signInEndpoint": "https://myapp.com/auth/signin",
  "signOutRedirects": ["https://myapp.com/signed-out"],
  "externalSignUp": "",
  "userInvitation": "https://myapp.com/invite",
  "passwordReset": "https://myapp.com/reset-password",
  "logoUri": "https://myapp.com/logo.png",
  "ssoSuccess": "https://myapp.com/admin/sso/success",
  "dirSyncSuccess": "",
  "logStreamsSuccess": "",
  "domainVerifySuccess": ""
}

Managing Redirects via the Dashboard

1. Navigate to Redirects in the dashboard sidebar
2. Each redirect setting is displayed as a card

Editing Single-Value Redirects

1. Click Edit on any single-value redirect card
2. Enter the URL in the inline input field
3. Press Enter to save or Escape to cancel
4. Changes are saved to the backend immediately

Editing Multi-Value Redirects

Multi-value fields (Redirect URIs, Sign-out redirects) support multiple URLs:

1. Each URI is displayed as a code block with edit and delete buttons
2. Click the pencil icon to edit an existing URI inline
3. Click the X icon to remove a URI
4. Click Add to add a new URI via an inline input field
5. Each modification is saved to the backend immediately

Admin Portal Redirects

1. Click Edit Admin Portal redirects to switch all 5 Admin Portal fields to edit mode simultaneously
2. Update the values as needed
3. Click Save to persist all changes or Cancel to revert

API Endpoints

The configPlugin exposes 2 redirect endpoints:

All endpoints require admin authentication.

Get Redirects

// POST /api/auth/banata/config/redirects/get
// Body: {}
// Response: RedirectsData object (or {} if not configured)

Save Redirects

// POST /api/auth/banata/config/redirects/save
// Body:
{
  "config": {
    "redirectUris": ["https://myapp.com/callback"],
    "appHomepage": "https://myapp.com",
    "signInEndpoint": "https://myapp.com/auth/signin",
    "signOutRedirects": ["https://myapp.com/signed-out"],
    "passwordReset": "https://myapp.com/reset-password"
  }
}

The save endpoint overwrites the entire configuration document. The dashboard sends the full config object on every save to ensure consistency.

Database Storage

Redirects are stored as a singleton row in the redirectConfig table in Convex:

// Simplified schema
defineTable({
  configJson: v.string(),    // JSON-serialized RedirectsData
  createdAt: v.float64(),
  updatedAt: v.float64(),
})

The entire redirect configuration lives in a single configJson string field. This makes atomic updates straightforward — read the blob, merge changes, write it back.

Using Redirects Programmatically

Via the Dashboard API Client

import { getRedirects, saveRedirects } from "@/lib/dashboard-api";
 
// Get current redirect configuration
const redirects = await getRedirects();
console.log(redirects.redirectUris);    // ["https://myapp.com/callback"]
console.log(redirects.appHomepage);     // "https://myapp.com"
 
// Update a single field (sends the full config)
const updated = await saveRedirects({
  ...redirects,
  appHomepage: "https://newdomain.com",
});

Redirect Validation

When configuring redirects, follow these rules:

1. Use HTTPS in production — HTTP redirect URIs are acceptable in development but should never be used in production
2. Use absolute URLs — All redirect URIs must be fully-qualified URLs (e.g., https://myapp.com/callback, not /callback)
3. Match your OAuth configuration — If using social OAuth providers, ensure the redirect URIs match what's registered with each provider
4. Keep multi-value lists minimal — Only add redirect URIs that are actively used by your clients

Security Considerations

1. Open redirect prevention — Only redirect to URIs that are explicitly configured. Banata Auth does not allow dynamic redirect targets.
2. Admin-only access — Redirect configuration requires admin authentication.
3. No wildcard support — Each redirect URI must be an exact match. Wildcards are not supported to prevent redirect hijacking.
4. HTTPS enforcement — In production, all redirect URIs should use HTTPS.

Troubleshooting

"Redirect URI mismatch"

The URL your client is requesting doesn't match any configured redirect URI. Check the Redirect URIs field in the dashboard and ensure the requested URL is in the list (exact match, including trailing slashes).

"Not configured" showing for all fields

Redirect configuration is empty until you save at least one value. Navigate to Redirects in the dashboard and configure the fields you need.

"Changes not persisting"

Redirect configuration is saved to the backend on every edit. If changes aren't persisting, check that you have admin privileges and that the Convex backend is running.

What's Next

• Domains — Configure custom domains for auth services
• Email & Password — Authentication flow that uses password reset redirects
• Social OAuth — OAuth flows that use redirect URIs