Versions Compared

Old Version 2

changes.mady.by.user Chitra Borker (Deactivated)

Saved on

compared with

New Version Current

changes.mady.by.user Simon Friend

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

There are two options to connect your project to your custom UI, using web API keys or using a token server. The easier and more secure option is using the web API keys method.

Note

If you have an orchestration server, you should use the advanced connection configuration on the Project Summary page. For details see Connecting using Token Server.

Connect Using API Keys

On a high level you would need to follow the below steps:

  1. Create and deploy your project from Digital DNA Studio > New Project.

  2. Create

a web

  1. an API key and assign it to your project from the settings cog > API Keys > Create API Key.

  2. To connect to your UI, pass in your web API key as an option when constructing your scene.

Creating API Key

to Connect to Digital Person

for Web UI

Create a web API key and assign it to your project. Once you create the key, you cannot edit it, you will need to revoke and create a new one instead.

new-web-api-key.movFrom

from the settings cog icon on the top right corner of the screen, select API Keys, andclick Create API Key.

On the

The new API Key

window, enter a

can then be assigned to your project with the specified domains it can be authenticated against.

Image Added

Field

Description

Name

Name for the new API key.

  • Select the scope as Web.

    • In the Assign Project field start

    Scope

    Choose Web for configuring a Web API Key.

    Assign Project

    Start typing the name of the project you wish to generate the API key for. Choose the name of the project from the dropdown list.


    You can search the project using the project name or project ID.

    Info

    Note: The project must be deployed before you create a Web API Key.

    5.

    I'm Developing Locally

    If you are developing locally for testing your project,

    click the toggle I’m Developing Locally

    enable this toggle and enter the Public IP Address IPv4 or IP46 with Subnet Mask.
    For example, 92.0.2.1/24 or 2001 : db8: 3333 : 4444 : 5555 : 6666 : 7777 : 8888.

    If developing locally, you

    You will also need to

    add

    supply your full localhost URL with port number as a Custom UI Domain: http://localhost:8000/

    Enable cross page persistence

    This toggle allows the session with Digital Person to continue across multiple pages on a domain or subdomain.

    6.

    See Session Persistence for more details.

    Custom UI Domain

    When you are ready for deploying the project, specify one or more web domain(s) in the Custom UI Domains field.

    7. Set the expiration date. Options available are 30, 60, 90, or never.

    8.

    Expiration

    The expiration for web API key is set to never by default. Until its revoked manually.

    On successful creation, the API key is displayed for you to save or copy. Once your API Key is generated, you can view it at any time on the API Keys view screen.

    Info

    You should revoke the key if it becomes inactive, lost, or compromised. For details see Revoke API Key.

    Creating API Key for Mobile UI

    Similar to the web API key, you can create API keys to connect to mobile UI (Android and iOS). In this case, select the scope as Mobile.

    Image Added

    Connect Using Token Server

    If you have an orchestration server, you should use the advanced connection configuration on the Project Summary page. For details see Connecting using Token Server.

    Related Topics

    Managing API Keys

    Field

    Description

    Name

    Name for the new API key.

    Scope

    Choose Mobile for configuring an API Key for Android or iOS UI.

    Assign Project

    Start typing the name of the project you wish to generate the API key for. Choose the name of the project from the dropdown list. You can search the project using the project name or project ID.

    Info

    Note: The project must be deployed before you create the API Key.

    Application IDs

    A unique name for your mobile app.


    Example: com.soulmachines.android.sample

    Expiration

    The expiration for API key is set to never by default. Until its revoked manually.

    Tips for API key usage

    1. Create one key for local development with IP restrictions and create another key for the public domain without IP restrictions. You should NOT combine them.

    2. If you are developing locally, we recommend you create your own API key. You can use a tool like Show My IP to find your IP address.

    3. Studio is not supporting IP range configuration right now, you would need to add all IP addresses manually.

    Troubleshooting

    Invalid API key error

    1. Check for Errors: If you're seeing an error about "Access blocked by CORS policy," it could be because the website URL where your Digital Person is hosted isn’t correctly set up in your API key settings. Make sure you’ve entered the full and exact URL, including the right subdomain (e.g., https://www/example.com vs https://example.com)

    2. API Key Setup: Double-check that the domains and IP addresses listed in your API key settings are correct. Double check CUSTOM UI DOMAINS and PUBLIC IP ADDRESSES & SUBNET MASK configuration in Soul Machines Studio, refer to the Tips for API key usage section.

    3. IP Address Issues: If you're developing locally and using a VPN, your IP address might change. Make sure all possible IP addresses are listed in the settings (PUBLIC IP ADDRESSES & SUBNET MASK).

    4. Intermittent Issues: If the API key works sometimes but not always, it could be a server issue. You can save the HAR file (a log of the problem) and share it with Soul Machines customer support (support@soulmachines.com) for more help.

    5. Switching Between Local and Remote Development: When moving from developing locally to deploying on a server, make sure you clear any previous IP address restrictions in the API settings. Just switching off the “I’m developing locally” option won’t remove them. To avoid issues, go into the API key settings, enter edit mode, and click “Update Key” again to reset everything.

      image-20240731-005816.pngImage Added


    No API key error but cannot connect, the widget always shows 95% loading progress

    • Check if your studio project is using HumanOS 2.4+ version, this is required for Session Persistence.

    JavaScript console error: blocked by CORS policy

    Access to fetch at [SoulMachines] has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

    • The request header referrer policy does not satisfy CORS policy. CORS policy at site level may be required. Example:

    Code Block
    <head><meta name="referrer" content="strict-origin-when-cross-origin"/></head>

    Related Topics

    Contents

    Table of Contents
    minLevel1
    maxLevel7