Embed the Dashboard

Embedding the dashboard is available to enterprise customers with Partner API access. Contact us to get started.

Summary/Quick Start

Get your API key from Settings → API Keys in your Answering Agent dashboard
Create a user via POST /api/v1/users, or attach an existing partner identity to an approved linked organization
Request an embed token for the intended organization_id and keep it server-side until rendering
Embed the dashboard using <iframe src="https://answeringagent.com/dashboard/embed?token=EMBED_TOKEN">
User’s browser loads embed → token is auto-exchanged for dashboard auth

X-API-KEY = your server only. embed_token = the compact browser input for one intended dashboard context.

The Answering Agent dashboard can be embedded into your website, providing a seamless customer support platform for your users. The embed system uses secure, compact tokens that authenticate users without exposing sensitive credentials.

Authentication Overview

The embed system involves two different authentication contexts:

Your Server (Partner)

Uses the X-API-KEY header to call the Partner API and retrieve embed tokens for your users.

User's Browser (End User)

Uses the embed_token which is automatically exchanged for embedded dashboard authentication.

Never expose your X-API-KEY in client-side code. The API key is for server-to-server communication only. End users only need the embed_token.

How Tokens Flow

Your server requests an embed token

Call the Partner API with your X-API-KEY to get an embed_token for a specific user and, for scoped viewers, a specific organization_id.

Your server passes the token to the browser

Inject the embed_token into the iframe URL.

The embed exchanges the token

When the iframe loads, Answering Agent exchanges the embed_token for embedded dashboard authentication.

User is authenticated

The embedded dashboard uses that authentication for page loads, navigation, and dashboard API calls. This happens automatically.

Getting Embed Tokens (Server-Side)

These endpoints require your X-API-KEY header and should only be called from your server, never from client-side code.

From User Creation

When you create a user from your server, the response includes an embed_token:

{
  "embed_token": "MTIzNDV8ZDgyZDk3Mzg1OTAxNTkzNA",
  "user": { /* user details */ },
  "team": { /* team details */ },
  "locations": [ /* locations */ ]
}

Managing Existing Tokens

For existing users, your server can retrieve or regenerate embed tokens. Include organization_id for scoped viewers and whenever a user has more than one eligible organization context:

Get Current Embed Token

GET /api/v1/users/{external_id}/embed-token?organization_id={organization_id}

cURL
Node.js
PHP

# Called from YOUR SERVER, not the browser
curl -H "X-API-KEY: your-api-key" \
     "https://answeringagent.com/api/v1/users/your-user-123/embed-token?organization_id=456"

// Server-side code (Express, Next.js API route, etc.)
const response = await fetch(
  'https://answeringagent.com/api/v1/users/your-user-123/embed-token?organization_id=456',
  {
    headers: {
      'X-API-KEY': process.env.ANSWERING_AGENT_API_KEY // Never expose this!
    }
  }
);
const { embed_token } = await response.json();
// Pass embed_token to your frontend template

// Server-side code (Laravel, etc.)
$response = Http::withHeaders([
    'X-API-KEY' => config('services.answering_agent.api_key'),
])->get('https://answeringagent.com/api/v1/users/your-user-123/embed-token', [
    'organization_id' => 456,
]);

$embedToken = $response->json('embed_token');
// Pass $embedToken to your view

Response:

{
  "embed_token": "MTIzNDV8ZDgyZDk3Mzg1OTAxNTkzNA",
  "user_id": "your-user-123",
  "organization_id": 456
}

Generate New Embed Token

POST /api/v1/users/{external_id}/embed-token?organization_id={organization_id}

For an organization-scoped viewer, rotation invalidates only that viewer relationship. Other approved organizations for the same identity keep working. Partner-provisioned users retain the legacy user-wide signing authority.For a partner-provisioned user, the signing authority remains user-wide even when organization_id selects the returned token’s team. The response includes "rotation_scope": "user", and every previously issued provisioned-organization compact token for that user must be replaced.

# Called from YOUR SERVER
curl -X POST \
     -H "X-API-KEY: your-api-key" \
     "https://answeringagent.com/api/v1/users/your-user-123/embed-token?organization_id=456"

Response:

{
  "embed_token": "OTg3NjV8YWJjZGVmZ2hpams1Njc4OTA",
  "user_id": "your-user-123",
  "organization_id": 456,
  "message": "New organization-scoped embed token generated successfully"
}

Multi-Organization Viewer Setup

An owner-linked organization must independently approve your partner account before you can attach viewers. Your server then reuses one partner-owned identity across approved organizations:

# Attach the same identity to two independently approved organizations
curl -X PUT -H "X-API-KEY: your-api-key" \
  https://answeringagent.com/api/v1/organizations/456/dashboard-viewers/account-manager-42

curl -X PUT -H "X-API-KEY: your-api-key" \
  https://answeringagent.com/api/v1/organizations/789/dashboard-viewers/account-manager-42

# Select one organization when issuing the iframe token
curl -H "X-API-KEY: your-api-key" \
  "https://answeringagent.com/api/v1/users/account-manager-42/embed-token?organization_id=789"

The scoped viewer can read all current and future locations in the selected organization. It cannot change settings, manage roles or members, call mutation endpoints, subscribe to operator realtime channels, or initiate recurring AI/model work.

Embedding the Dashboard

Embed the dashboard with an iframe for complete DOM isolation:

<iframe
  src="https://answeringagent.com/dashboard/embed?token=MTIzNDV8ZDgyZDk3Mzg1OTAxNTkzNA"
  width="100%"
  height="600px"
  frameborder="0"
  style="border: none;">
</iframe>

Benefits:

Zero JavaScript required - just paste the iFrame
Complete DOM isolation from your page
Works with strict Content Security Policies
No conflicts with your site’s CSS or JavaScript
Easy to implement in any CMS or page builder

Partner theme:

<iframe
  src="https://answeringagent.com/dashboard/embed?token=YOUR_TOKEN&theme=sonnys"
  width="100%"
  height="600px"
  frameborder="0">
</iframe>

Supported theme values are sonnys and optspot. Omit theme for the default Answering Agent dashboard styling. Existing iframe embeds that use https://answeringagent.com/dashboard.html?token=... remain supported and run through the same embed exchange. Existing script embeds that load https://answeringagent.com/embed.js also remain supported; the script creates a /dashboard/embed iframe for you. New installs should use the direct /dashboard/embed iframe.

Quick Start Checklist

iFrame tag with src pointing to /dashboard/embed?token=YOUR_TOKEN
Valid embed token in the URL query parameter
Optional partner theme with theme=sonnys or theme=optspot

That’s it. The iframe route automatically exchanges the embed_token for dashboard authentication and the dashboard enforces the selected organization scope. When switching organizations, request a token for the new organization_id and replace the existing iframe src. Running multiple same-origin organization embeds simultaneously in one browser session is not a supported isolation boundary. Custom API URLs are restricted to the default API origin, the playground API origin, or origins listed in the Next.js EMBED_API_URL_ALLOWLIST environment variable.

Dynamic Token Integration

For production applications, your server should fetch embed tokens and pass them to the frontend.

Server-Side Endpoint

Create an endpoint in your backend that fetches the embed token:

Node.js / Express
PHP / Laravel

// routes/embed.js - YOUR SERVER
app.get('/api/embed-token', async (req, res) => {
  // 1. Authenticate your own user (your auth system)
  const user = await authenticateRequest(req);
  if (!user) return res.status(401).json({ error: 'Unauthorized' });

  // 2. Get the user's external ID (their ID in Answering Agent)
  const externalId = user.answeringAgentId;
  const organizationId = authorizeOrganization(req, user);

  // 3. Fetch embed token from Answering Agent using YOUR API key
  const response = await fetch(
    `https://answeringagent.com/api/v1/users/${externalId}/embed-token?organization_id=${organizationId}`,
    {
      headers: {
        'X-API-KEY': process.env.ANSWERING_AGENT_API_KEY
      }
    }
  );

  const { embed_token } = await response.json();
  res.json({ embed_token });
});

// routes/api.php - YOUR SERVER
Route::get('/embed-token', function (Request $request) {
    // 1. Authenticate your own user (your auth system)
    $user = $request->user();

    // 2. Get the user's external ID (their ID in Answering Agent)
    $externalId = $user->answering_agent_id;
    $organizationId = authorizeOrganization($request, $user);

    // 3. Fetch embed token from Answering Agent using YOUR API key
    $response = Http::withHeaders([
        'X-API-KEY' => config('services.answering_agent.api_key'),
    ])->get("https://answeringagent.com/api/v1/users/{$externalId}/embed-token", [
        'organization_id' => $organizationId,
    ]);

    return response()->json([
        'embed_token' => $response->json('embed_token'),
    ]);
})->middleware('auth');

Client-Side Integration

Your frontend calls your backend (not Answering Agent directly):

async function loadAnsweringAgentDashboard() {
  try {
    // Call YOUR backend endpoint (which uses X-API-KEY internally)
    const response = await fetch('/api/embed-token', {
      headers: {
        'Authorization': `Bearer ${yourSessionToken}` // Your auth
      }
    });

    const { embed_token } = await response.json();

    // Set the iframe URL. The iframe handles token exchange automatically.
    const frame = document.getElementById('answering-agent-dashboard');
    frame.src = `https://answeringagent.com/dashboard/embed?token=${encodeURIComponent(embed_token)}`;
  } catch (error) {
    console.error('Failed to load dashboard:', error);
  }
}

The iframe route automatically handles exchanging the embed_token for dashboard auth. You don’t need to call /api/validate-embed-token yourself.

React Component Example

function AnsweringAgentDashboard({ organizationId }) {
  const [embedToken, setEmbedToken] = useState(null);
  const [error, setError] = useState(null);

  useEffect(() => {
    // Call YOUR backend (which calls Partner API with X-API-KEY)
    fetch(`/api/embed-token?organization_id=${encodeURIComponent(organizationId)}`)
      .then(res => res.json())
      .then(data => setEmbedToken(data.embed_token))
      .catch(err => setError(err.message));
  }, [organizationId]);

  if (error) return <div>Failed to load dashboard</div>;
  if (!embedToken) return <div>Loading...</div>;

  return (
    <iframe
      id="answering-agent-dashboard"
      src={`https://answeringagent.com/dashboard/embed?token=${encodeURIComponent(embedToken)}`}
      style={{ width: '100%', height: '600px', border: 0 }}
    />
  );
}

Your /api/embed-token endpoint should authenticate the request using your own auth system, then call the Answering Agent Partner API with your X-API-KEY.

Security Features

Token Types

Token	Who Uses It	How It’s Sent	How to Get It
X-API-KEY	Your server	`X-API-KEY` header	Dashboard → Settings → API Keys
embed_token	User’s browser	URL param	Partner API response
auth_token	Answering Agent embed runtime	Server-only bearer auth for iframes	Auto-exchanged from embed_token

Compact Tokens

URL-safe base64 encoding without padding
Optimized for query parameters and data attributes

Secure Validation

Uses HMAC-SHA256 for cryptographic integrity
Scoped tokens are tied to a specific user, partner, organization, grant, and authority generation
Every scoped request revalidates current authority before it can read organization data

Token Lifecycle

Compact tokens have no built-in expiry but can be invalidated immediately
Exchanged dashboard bearers expire after 15 minutes
Scoped viewers can have independent tokens for multiple organizations
Detach, grant disable/revoke, partner-link revoke, membership removal, or user deletion invalidates the affected scoped authority

Error Handling

Invalid or Expired Tokens

If an embed token is invalid, the embedded dashboard will show an authentication error. Common causes:

Token was invalidated by generating a new one
The viewer was detached or its owner-approved grant, partner link, membership, or user was revoked
Token is malformed or corrupted
User account was deleted or suspended

Missing Configuration

If the embed container is not properly configured, you may see:

Console warnings about missing configuration
Dashboard not loading or appearing blank
Authentication errors

Best Practices

Server-Side (Your Backend)

Never expose X-API-KEY - Keep your API key in server-only secret storage
Proxy embed tokens - Your backend should fetch tokens and pass them to the frontend
Bind requests to organization_id - Authorize the organization in your own backend before requesting its scoped token
Replace the iframe when switching - Request a fresh organization token and update the single iframe src
Rotate on security events - Rotate only the affected organization relationship when possible

Client-Side (User’s Browser)

Use iframe embeds - Use /dashboard/embed?token=... for the Next.js dashboard experience
Handle errors gracefully - Show fallback UI if embedding fails
Use HTTPS only - Never transmit tokens over insecure connections

Troubleshooting

Dashboard Won’t Load

Verify the embed token is valid by checking the Partner API response
Confirm the iframe src includes /dashboard/embed?token=...
Check browser console for JavaScript errors
Ensure the iframe has proper dimensions and is visible

Authentication Errors

The embed token may have been invalidated - fetch a new one from the Partner API
For a multi-organization user, verify your server requested the intended organization_id
Check that your server is using the correct X-API-KEY
Verify the user exists in Answering Agent
Ensure the iframe URL includes a valid token parameter

Configuration Errors

Verify the iframe src points to https://answeringagent.com/dashboard/embed
Check that the token query parameter contains a valid embed token
Monitor network requests to verify API calls are reaching the correct endpoint

Performance Issues

Cache embed tokens in your backend to avoid repeated Partner API calls
Monitor iframe sizing to prevent layout shifts

Getting Started

Guides

POS Integrations

API Reference

API Playground

Summary/Quick Start

Authentication Overview

Your Server (Partner)

User's Browser (End User)

How Tokens Flow

Getting Embed Tokens (Server-Side)

From User Creation

Managing Existing Tokens

Get Current Embed Token

Generate New Embed Token

Multi-Organization Viewer Setup

Embedding the Dashboard

Quick Start Checklist

Dynamic Token Integration

Server-Side Endpoint

Client-Side Integration

React Component Example

Security Features

Token Types

Compact Tokens

Secure Validation

Token Lifecycle

Error Handling

Invalid or Expired Tokens

Missing Configuration

Best Practices

Server-Side (Your Backend)

Client-Side (User’s Browser)

Troubleshooting

Dashboard Won’t Load

Authentication Errors

Configuration Errors

Performance Issues

​Summary/Quick Start

​Authentication Overview

Your Server (Partner)

User's Browser (End User)

​How Tokens Flow

​Getting Embed Tokens (Server-Side)

​From User Creation

​Managing Existing Tokens

​Get Current Embed Token

​Generate New Embed Token

​Multi-Organization Viewer Setup

​Embedding the Dashboard

​Quick Start Checklist

​Dynamic Token Integration

​Server-Side Endpoint

​Client-Side Integration

​React Component Example

​Security Features

​Token Types

​Compact Tokens

​Secure Validation

​Token Lifecycle

​Error Handling

​Invalid or Expired Tokens

​Missing Configuration

​Best Practices

​Server-Side (Your Backend)

​Client-Side (User’s Browser)

​Troubleshooting

​Dashboard Won’t Load

​Authentication Errors

​Configuration Errors

​Performance Issues

Summary/Quick Start

Authentication Overview

How Tokens Flow

Getting Embed Tokens (Server-Side)

From User Creation

Managing Existing Tokens

Get Current Embed Token

Generate New Embed Token

Multi-Organization Viewer Setup

Embedding the Dashboard

Quick Start Checklist

Dynamic Token Integration

Server-Side Endpoint

Client-Side Integration

React Component Example

Security Features

Token Types

Compact Tokens

Secure Validation

Token Lifecycle

Error Handling

Invalid or Expired Tokens

Missing Configuration

Best Practices

Server-Side (Your Backend)

Client-Side (User’s Browser)

Troubleshooting

Dashboard Won’t Load

Authentication Errors

Configuration Errors

Performance Issues