Embed the reader assistant on another site

The reader assistant does not have to live only inside the published documentation site. Doxbrix also lets you create project-specific assistant keys and embed the assistant in another web property.

This guide explains how to set that up professionally so the assistant is secure, environment-specific, and easy to manage over time.

Who this is for

• teams embedding docs assistance into a product site, marketing site, or support portal
• teams that want a docs-aware assistant outside the main documentation shell
• project admins managing assistant access and operational control

What you will use

Inside Project settings → Assistant, the API Keys & Embed area lets you:

• Create key
• define Allowed origins
• review Existing keys
• revoke keys when they are no longer needed

When a key is created, Doxbrix also shows an embed snippet that includes the new assistant key.

Before you begin

Make sure:

• the Reader assistant is configured the way you want readers to experience it
• the target website is known and stable
• you know which domains should be allowed to host the assistant

If the assistant itself is not ready yet, configure that first. Embedding an unfinished assistant simply exposes a poor experience in more places.

Step 1 — Confirm the assistant experience

Before you create keys, review the main assistant settings in Assistant.

Check:

• Assistant status
• Assistant name
• Welcome message
• Starter questions
• Assistant engine
• Response length
• Fallback mode
• Fallback message
• Show citations

The embed will inherit the project’s assistant behavior, so the quality of the embedded experience depends on these settings.

Step 2 — Create a key with a clear label

In API Keys & Embed, use Create key.

For the label, describe where the key will be used.

Good examples:

• Marketing site embed
• Support portal assistant
• In-app help widget

This matters because Existing keys may grow over time, and clean labels make troubleshooting and revocation much easier.

Step 3 — Set Allowed origins carefully

Use Allowed origins for browser and embed usage.

Enter one origin per line, such as:

• https://www.example.com
• https://help.example.com

Allowed origins are important because they restrict where browser-based requests can come from.

Use them when:

• embedding on a public website
• embedding on a support center outside the main docs property
• separating production and staging environments cleanly

If you are using a server-to-server pattern instead, the field can remain empty. The interface explicitly notes that empty origins are suitable for server-side use.

Step 4 — Create the key and capture the one-time reveal

After you click Create key, Doxbrix shows:

• the full assistant key
• an embed snippet that references that key

This is the only time the full key is shown.

At that moment:

• copy the key into your approved secret storage if needed
• copy the embed snippet into the target implementation workflow
• record which site and environment the key belongs to

Step 5 — Add the embed snippet to the target site

Use the generated snippet in the target web property exactly as intended for that environment.

Treat the embed rollout like any other production integration:

• test in staging first
• confirm the correct domain is allowed
• validate that the assistant appears where users expect it
• check that it does not conflict with existing support or chat surfaces

Step 6 — Validate the embedded experience end to end

Once the snippet is in place, test the assistant as a real user.

Check:

• the assistant loads on the target site
• the key is accepted from that origin
• the assistant responds with the expected tone and scope
• citations display correctly if Show citations is enabled
• fallback behavior is sensible when the assistant cannot answer

Also test a disallowed origin or environment to confirm the key is properly constrained.

Step 7 — Monitor and manage Existing keys

The Existing keys list helps you manage ongoing usage.

For each key, Doxbrix surfaces useful summary information such as:

• key prefix
• label
• number of allowed origins or server-only status
• request count
• revoked state

Use this list to spot:

• old embeds that should be retired
• duplicate keys for the same surface
• unexpected usage growth
• staging keys that were never cleaned up

Step 8 — Revoke and replace keys cleanly

When a site changes, an environment is retired, or you suspect a key is exposed, revoke it and replace it deliberately.

Use this process:

1. create a replacement key
2. update the target site
3. validate the new key
4. revoke the old key

This avoids unnecessary reader disruption and keeps assistant access understandable.

Recommended rollout pattern

For most teams:

• use a separate key per site or environment
• restrict Allowed origins tightly
• label keys clearly
• test both allowed and disallowed origins
• revoke old keys instead of reusing them indefinitely

Related pages