Quick Start - Doshi API

Overview

Doshi webview authentication uses a secure two-step process:

Generate a custom token by calling the Doshi API with your API key
Pass the token to the iframe using postMessage or query parameters

IP Whitelisting Required: Your server’s IP address must be whitelisted to access the Doshi API. Contact hello@doshi.app with your server IP addresses to get started.

Get API Key & Whitelist IP

Contact hello@doshi.app to:

Receive your API key
Whitelist your server IP address(es)

Generate Custom Token

Call the authentication endpoint with your API key from your whitelisted server

Embed Webview

Pass the custom token to the Doshi Frontend using postMessage or query parameters

User Signs In

Doshi handles the sign-in process, including 2FA if enabled

These examples use the production hosts. To test against sandbox, use https://sandbox.embed.doshi.app (and https://sandbox.api.doshi.app for the API) — your client token works in both. See Environments.

Authentication Flow

Step 1: Generate Custom Token

Call the authentication endpoint with your API key:

curl -X POST https://api.doshi.app/client/auth/custom-token \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Access-Type: client" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "partnerUserId": "partner_123",
    "firstName": "John",
    "lastName": "Doe",
    "branchId": "branch_789"
  }'

Required Headers:

Authorization: Bearer YOUR_API_KEY
Access-Type: client
Content-Type: application/json

API Parameters

Required (at least one):

email - User’s email address
partnerUserId - Your internal user ID

Optional:

firstName - User’s first name
lastName - User’s last name
branchId - Branch or location identifier

You must provide either email OR partnerUserId (or both). All other fields are optional.

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

See the full API reference for details.

Setting the Starting Learning Path

By default, a new user picks their own learning path the first time they open Doshi. To skip that screen and drop them straight into a specific set of lessons, pass a pathId when you mint the token.

pathId is only accepted by /client/auth/token — not by /client/auth/custom-token, which ignores it. Use /client/auth/token when you need a starting path.

Create the path

In the dashboard, go to Paths → Create, then add the courses and lessons you want the user to see.

Copy the path ID

On the path’s card, open the ⋯ menu and choose Copy ID. The ID is also the last segment of the path’s URL (/paths/<pathId>).

Pass it when generating the token

Include the ID as pathId in the token request.

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",
    "pathId": "YOUR_PATH_ID"
  }'

The user now lands directly in the lessons on that path, with no path-selection screen.

Behaviour and limits

Sets the initial path only. If the user already has a path, pathId is ignored — existing users are never moved. It is not a way to switch someone’s path later.
Don’t combine it with segment. The two write to different places, so sending both leaves the path-selection screen in place. Use one or the other.
The ID isn’t validated. An incorrect ID is accepted without an error and leaves the user without usable content, so confirm the flow on sandbox before going live.
Must be 2–50 characters.
Works with the 2FA flow.

pathId decides which lessons the user starts on. segment is different — it narrows which paths a user is offered when you run several paths under one organization, and still lets them choose.

Step 2: Pass Token to Doshi Frontend

Pass the nonce token to the Doshi Frontend using one of two methods:

postMessage (Recommended)

Secure, real-time communication for sensitive data

Query Parameters

Simple URL-based authentication

Frontend Parameters

Required:

token - The nonce token from the API

Optional:

email - User’s email address
segment - For handling multiple learning paths
branchId - Branch or location identifier

2FA Parameters (Optional)

When 2FA is enabled, pass these additional parameters: All 2FA fields are required when is2FaEnabled is true:

is2FaEnabled - Set to true
dob - Date of birth (YYYY-MM-DD)
organizationId - Your organization ID
partnerUserId - Your internal user ID
firstName - User’s first name
lastName - User’s last name

string

required

The nonce token received from the API

string

User’s email address (optional)

string

Used for handling multiple learning paths under the same organization (optional)

string

Branch or location identifier (optional)

boolean

Set to true to enable 2FA flow (optional, but if true, all 2FA fields below are required)

string

User’s date of birth - YYYY-MM-DD format (required when is2FaEnabled is true)

string

Your organization ID (required when is2FaEnabled is true)

string

Your internal user ID (required when is2FaEnabled is true)

string

User’s first name (required when is2FaEnabled is true)

string

User’s last name (required when is2FaEnabled is true)

When 2FA is enabled, the Doshi Frontend automatically handles the OTP send and verification flow. You don’t need to call the OTP endpoints separately.

Step 3: Session Management

Once authenticated, the Doshi Frontend automatically manages the session:

ID Token TTL: 1 hour
Refresh Token TTL: 12 hours
Auto-refresh: Tokens are refreshed automatically

No additional action required from your application!

Quick Example

React with postMessage

import React, { useEffect, useState } from "react";

const DoshiEmbed = () => {
  const [token, setToken] = useState<string | null>(null);

  useEffect(() => {
    // Step 1: Get nonce token from API
    async function authenticate() {
      const response = await fetch('https://api.doshi.app/client/auth/custom-token', {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Access-Type': 'client',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          email: 'user@example.com',  // Required (or partnerUserId)
          partnerUserId: 'partner_123', // Optional (but one of email/partnerUserId required)
          branchId: 'branch_789'        // Optional
        })
      });
      
      const data = await response.json();
      setToken(data.token);
    }

    authenticate();
  }, []);

  useEffect(() => {
    if (!token) return;

    // Step 2: Listen for PING from Doshi Frontend
    const handleMessage = (event: MessageEvent) => {
      if (event.origin !== 'https://embed.v2.doshi.app') return;
      
      const data = typeof event.data === "string" 
        ? JSON.parse(event.data) 
        : event.data;

      if (data.type === "PING") {
        // Step 3: Send token to Doshi Frontend
        const iframe = document.querySelector("iframe");
        if (iframe?.contentWindow) {
          iframe.contentWindow.postMessage(
            JSON.stringify({
              token,               // Required
              email: 'user@example.com',  // Optional
              segment: 'premium',         // Optional
              branchId: 'branch_789',     // Optional
              type: "AUTH"
            }),
            "https://embed.v2.doshi.app"
          );
        }
      }
    };

    window.addEventListener("message", handleMessage);
    return () => window.removeEventListener("message", handleMessage);
  }, [token]);

  if (!token) {
    return <div>Loading...</div>;
  }

  return (
    <iframe
      src="https://embed.v2.doshi.app"
      className="w-full h-screen"
      frameBorder="0"
      allowFullScreen
    />
  );
};

export default DoshiEmbed;

React with Query Parameters

import React, { useEffect, useState } from "react";

const DoshiEmbed = () => {
  const [iframeUrl, setIframeUrl] = useState<string | null>(null);

  useEffect(() => {
    async function authenticate() {
      // Step 1: Get nonce token
      const response = await fetch('https://api.doshi.app/client/auth/custom-token', {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Access-Type': 'client',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          email: 'user@example.com',      // Required (or partnerUserId)
          partnerUserId: 'partner_123'    // Optional
        })
      });
      
      const data = await response.json();
      
      // Step 2: Build URL with token
      const params = new URLSearchParams({
        token: data.token,              // Required
        email: 'user@example.com',      // Optional
        segment: 'premium',             // Optional
        branchId: 'branch_789'          // Optional
      });
      
      setIframeUrl(`https://embed.v2.doshi.app?${params.toString()}`);
    }

    authenticate();
  }, []);

  if (!iframeUrl) {
    return <div>Loading...</div>;
  }

  return (
    <iframe
      src={iframeUrl}
      className="w-full h-screen"
      frameBorder="0"
      allowFullScreen
    />
  );
};

export default DoshiEmbed;

With 2FA Enabled

const authData = {
  token: data.token,                    // Required
  email: 'user@example.com',            // Optional
  segment: 'premium',                   // Optional
  branchId: 'branch_789',               // Optional
  // All fields below are required when is2FaEnabled is true
  is2FaEnabled: true,
  dob: '1990-01-15',
  organizationId: 'org_123',
  partnerUserId: 'partner_123',
  firstName: 'John',
  lastName: 'Doe'
};

// The Doshi Frontend will automatically show OTP screen and handle verification

Next Steps

postMessage Method

Detailed postMessage implementation

Query Parameters

URL-based authentication guide

Security

Security best practices

Need Help?

Contact Support

Get your API key or ask questions: hello@doshi.app

​Overview

​Authentication Flow

​Step 1: Generate Custom Token

​API Parameters

​Setting the Starting Learning Path

​Behaviour and limits

​Step 2: Pass Token to Doshi Frontend

postMessage (Recommended)

Query Parameters

​Frontend Parameters

​2FA Parameters (Optional)

​Step 3: Session Management

​Quick Example

​React with postMessage

​React with Query Parameters

​With 2FA Enabled

​Next Steps

postMessage Method

Query Parameters

Security

​Need Help?

Contact Support

Overview

Authentication Flow

Step 1: Generate Custom Token

API Parameters

Setting the Starting Learning Path

Behaviour and limits

Step 2: Pass Token to Doshi Frontend

Frontend Parameters

2FA Parameters (Optional)

Step 3: Session Management

Quick Example

React with postMessage

React with Query Parameters

With 2FA Enabled

Next Steps

Need Help?