Skip to main content

​
Introduction

Doshi provides a secure webview authentication system that uses a two-step process:
  1. Generate a custom token from the Doshi API using your API key
  2. Pass the token to the embedded Doshi iframe
This guide explains the authentication methods available after you’ve obtained your custom token.
New to Doshi authentication? Start with the Quick Start Guide for a complete walkthrough.

​
Authentication Methods

After obtaining your custom token from the API, you can pass it to the iframe using two methods:

postMessage API

Recommended for productionReal-time, secure cross-origin communication. Best for sensitive data and dynamic flows.

Query Parameters

Simple implementationURL-based authentication. Best for quick setup and debugging.

​
How It Works

1

Client Calls API

Your backend calls /client/auth/token with your API key to generate a custom token
2

Pass Token to Iframe

Your frontend passes the token to the Doshi iframe using postMessage or query parameters
3

User Authenticates

Doshi iframe handles user authentication, including 2FA if enabled
4

Session Active

User session is managed automatically (1hr ID token + 12hr refresh token)

​
Data Structure

​
Required Parameter

interface AuthData {
  token: string; // Custom token from API (required)
}

​
Optional Parameters

interface AuthData {
  token: string;              // Required
  email?: string;             // User's email
  segment?: string;           // For multiple paths in same org
  branchId?: string;          // Branch/location identifier
  
  // 2FA Parameters (when is2FaEnabled is true)
  is2FaEnabled?: boolean;     // Enable 2FA flow
  dob?: string;               // Date of birth (YYYY-MM-DD)
  organizationId?: string;    // Your organization ID
  partnerUserId?: string;     // Your internal user ID
  firstName?: string;         // User's first name
  lastName?: string;          // User's last name
}

​
Basic Setup

​
1. Get Your API Key

Contact [email protected] to receive your static API key.

​
2. Generate Custom Token

curl -X POST https://api.doshi.app/client/auth/token \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Access-Type: client" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'
See the full API reference.

​
3. Embed the Webview

<iframe
  src="https://embed.v2.doshi.app"
  class="w-full h-screen"
  frameborder="0"
  allowfullscreen
></iframe>

​
4. Pass Token to Iframe

Choose your preferred method: 
// Listen for PING from iframe
window.addEventListener("message", (event) => {
  if (event.data.type === "PING") {
    iframe.contentWindow.postMessage(
      JSON.stringify({
        token: "your_custom_token",
        email: "[email protected]",
        type: "AUTH"
      }),
      "https://embed.v2.doshi.app"
    );
  }
});

​
2FA Support

When 2FA is enabled for your organization, pass the required user information: 
const authData = {
  token: "your_custom_token",
  email: "[email protected]",
  is2FaEnabled: true,
  dob: "1990-01-15",
  organizationId: "org_123",
  partnerUserId: "partner_123",
  firstName: "John",
  lastName: "Doe"
};
The Doshi iframe will automatically:
  1. Display the OTP input screen
  2. Send the OTP to the user’s phone
  3. Verify the OTP
  4. Complete authentication
You don’t need to call /client/auth/send-otp or /client/auth/verify-otp separately. The iframe handles the entire 2FA flow.

​
Session Management

Once authenticated, sessions are managed automatically:
  • ID Token: Valid for 1 hour
  • Refresh Token: Valid for 12 hours
  • Auto-refresh: Tokens are refreshed automatically by the iframe
No action required from your application!

​
Parameter Details

​
segment

The segment parameter is used for handling multiple learning paths under the same organization. This allows you to direct users to different educational journeys based on their needs or preferences. Example: 
{
  segment: "premium",  // or "basic", "enterprise", etc.
}

​
branchId

Used to identify which branch or location the user belongs to within your organization. Example: 
{
  branchId: "branch_789",  // Your branch identifier
}

​
Mobile App Considerations

When embedding Doshi Frontend in mobile apps:

Disable Zoom

Prevent pinch-to-zoom for consistent UI

Handle Keyboard

Adjust layout when keyboard opens

Handle Links

Implement link click callbacks
See Best Practices for detailed mobile implementation guides.

​
Next Steps

Quick Start

Complete walkthrough with examples

Security

Security best practices

postMessage Guide

Detailed postMessage implementation