UNITHdocs
Sign inarrow_forward
API

Managing Allowed Origins for Digital Humans

This section details the process of configuring domain whitelisting for your embedded digital human. This allows you to define the approved websites where the digital human is authorized to operate.

The /head/{id}/allowed-origins endpoint controls which domains can access the digital human API. The default value is *, meaning that requests from any origin are permitted. While convenient for initial setup, restricting allowedOrigins to a whitelist of known domains is crucial for enhanced security in production deployments.

warning_amber

To whitelist domains, you must specify the unique head ID, as origin whitelisting is managed individually for each digital human.

Curl example:

code
curl -X 'PUT' \
  'https://platform-api.unith.ai/head/yourHeadID/allowed-origins' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer yourBearerToken' \
  -H 'Content-Type: application/json' \
  -d '[
  "yourDomain"
]'

Restricting the origin

To allow access only from https://www.unith.ai, configure the origins parameter as follows:

[“https://www.unith.ai“]

To permit access from both https://www.unith.ai and https://www.unith2.ai, use the following configuration:

[“https://www.unith.ai“, “https://www.unith2.ai“]

To allow access from any origin, effectively making the digital human public again, set the origins parameter to:

[“*“]

Iframe

The same principles of origin restriction apply to embedding the digital human within an iframe.

To control which domains are allowed to embed the digital human via an iframe, you can manage a separate whitelist of origins specifically for iframe integration.

Use the following endpoint /head/{id}/iframe/allowed-origins in order to set specific domains for your digital human using id.

code
curl -X 'PUT' \
  'https://platform-api.unith.ai/head/yourHeadId/iframe/allowed-origins' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer yourBearerToken' \
  -H 'Content-Type: application/json' \
  -d '["www.yourdomain.ai"]'

interFace

To restrict domains, you can do so within interFace itself.

First, navigate to your "dashboard" and click the edit button (the pencil icon) on any of your deployed digital humans. This will open a new window where you can control all aspects of your digital human's configuration. Within this window, go to the "security" section, enable the "restrict domains" toggle, and then add the specific domains you wish to restrict.

warning_amber

Please be aware that when configuring allowed iframe origins /head/{id}/iframe/allowed-origins, you must also include https://chat.unith.ai in the general allowed origins /head/{id}/allowed-origins.

Also, note that you might not be able to preview the digital human directly unless you've specified its domain in the allowed domains list.

Edit->Security
Security
warning_amber

When adding new domains, it's crucial to use the correct format. Here's an example to follow: https://www.unith.ai

info

To test your video-only Digital Human in a local development environment, you must whitelist your local domains directly via the API, as the user interface (interFace) does not support local domain configuration for this specific purpose.

To whitelist your local development URL(s), use the following endpoint:

  • Endpoint: /head/yourHeadId/iframe/allowed-origins
  • Method: PUT
  • Description: Adds or updates the list of allowed origins (domains) for your Digital Human's iframe embedding.
  • Request Headers:
    • Accept: application/json
    • Authorization: Bearer <yourBearerToken> (Replace <yourBearerToken> with your actual authentication bearer token)
    • Content-Type: application/json
  • Request Body:
    • A JSON array containing the local host URL(s) you wish to whitelist.
  • Curl Example:
code
curl -X 'PUT' \
  'https://platform-api.unith.ai/head/yourHeadId/iframe/allowed-origins' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer yourBearerToken' \
  -H 'Content-Type: application/json' \
  -d '[
  "http://localhost:3000",
  "http://127.0.0.1:8080"
]'

Replace yourHeadId with the actual ID of your Digital Human head and yourBearerToken with your valid authentication token. Include all relevant local development URLs (e.g., http://localhost:3000, http://127.0.0.1:8080) that your application will use.

scheduleLast updated Feb 18, 2026