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

# Webview Authentication Overview

> Learn how to implement secure webview-based authentication in your web application

## 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.

<Note>
  New to Doshi authentication? Start with the [Quick Start Guide](/webview/quickstart) for a complete walkthrough.
</Note>

## Authentication Methods

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

<CardGroup cols={2}>
  <Card title="postMessage API" icon="message" href="/webview/postmessage">
    **Recommended for production**

    Real-time, secure cross-origin communication. Best for sensitive data and dynamic flows.
  </Card>

  <Card title="Query Parameters" icon="link" href="/webview/query-parameters">
    **Simple implementation**

    URL-based authentication. Best for quick setup and debugging.
  </Card>
</CardGroup>

## How It Works

<Steps>
  <Step title="Client Calls API">
    Your backend calls `/client/auth/token` with your API key to generate a custom token
  </Step>

  <Step title="Pass Token to Iframe">
    Your frontend passes the token to the Doshi iframe using postMessage or query parameters
  </Step>

  <Step title="User Authenticates">
    Doshi iframe handles user authentication, including 2FA if enabled
  </Step>

  <Step title="Session Active">
    User session is managed automatically (1hr ID token + 12hr refresh token)
  </Step>
</Steps>

## Data Structure

### Required Parameter

```typescript theme={null}
interface AuthData {
  token: string; // Custom token from API (required)
}
```

### Optional Parameters

```typescript theme={null}
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 [hello@doshi.app](mailto:hello@doshi.app) to receive your static API key.

### 2. Generate Custom Token

```bash theme={null}
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": "user@example.com"
  }'
```

See the [full API reference](/api-reference/auth/get-custom-authentication-token).

### 3. Embed the Webview

<Note>
  Examples use the production host. To test, swap it for
  `https://sandbox.embed.doshi.app` — the same client token works in both. See
  [Environments](/webview/environments).
</Note>

```html theme={null}
<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:

<CodeGroup>
  ```tsx postMessage theme={null}
  // Listen for PING from iframe
  window.addEventListener("message", (event) => {
    if (event.data.type === "PING") {
      iframe.contentWindow.postMessage(
        JSON.stringify({
          token: "your_custom_token",
          email: "user@example.com",
          type: "AUTH"
        }),
        "https://embed.v2.doshi.app"
      );
    }
  });
  ```

  ```tsx Query Parameters theme={null}
  const params = new URLSearchParams({
    token: "your_nonce_token",
    email: "user@example.com",
    segment: "premium"
  });

  const iframeUrl = `https://embed.v2.doshi.app?${params.toString()}`;
  ```
</CodeGroup>

## 2FA Support

When 2FA is enabled for your organization, pass the required user information:

```typescript theme={null}
const authData = {
  token: "your_custom_token",
  email: "user@example.com",
  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

<Note>
  You don't need to call `/client/auth/send-otp` or `/client/auth/verify-otp` separately. The iframe handles the entire 2FA flow.
</Note>

## 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:**

```typescript theme={null}
{
  segment: "premium",  // or "basic", "enterprise", etc.
}
```

### branchId

Used to identify which branch or location the user belongs to within your organization.

**Example:**

```typescript theme={null}
{
  branchId: "branch_789",  // Your branch identifier
}
```

## Mobile App Considerations

When embedding Doshi Frontend in mobile apps:

<CardGroup cols={3}>
  <Card title="Disable Zoom" icon="mobile">
    Prevent pinch-to-zoom for consistent UI
  </Card>

  <Card title="Handle Keyboard" icon="keyboard">
    Adjust layout when keyboard opens
  </Card>

  <Card title="Handle Links" icon="link">
    Implement link click callbacks
  </Card>
</CardGroup>

See [Best Practices](/webview/best-practices) for detailed mobile implementation guides.

## Next Steps

<CardGroup cols={3}>
  <Card title="Quick Start" icon="rocket" href="/webview/quickstart">
    Complete walkthrough with examples
  </Card>

  <Card title="Security" icon="shield" href="/webview/security">
    Security best practices
  </Card>

  <Card title="postMessage Guide" icon="message" href="/webview/postmessage">
    Detailed postMessage implementation
  </Card>
</CardGroup>