Connecting using Token Server

Owned by Jon Borromeo (Deactivated)
Last updated: Apr 24, 2024 by Simon Friend
2 min read

There are two options to connect your project to your custom UI, using web API keys or using a Token Server. The easier and least complex option is using the web API keys method.

Soul Machines uses an SSK to grant your UI access to our session servers. By signing a JSON Web Token (JWT) with the SSK, our servers will grant you access.

What is a Shared Secret Key

A Shared Secret Key (SSK) is a cryptographic key or data that is only known to the parties involved in a secured communication. The shared secret can be anything from passwords or passphrases to a random number or an array of randomly chosen data.

Why would I use a Shared Secret Key?

By accessing our servers, you will be able to host our Digital Person conversational experiences on your website and optionally connect the Digital Person to a custom backend. 

Digital DNA Studio provides you with the three pieces of information that you need to connect:

  1. Digital Person Server domain name is also called the Token Server or Session Server.

  2. Key Name; this is called the “issuer” within the JWT 

  3. Private Key

image-20240424-014458.png

The private key must be used to sign the JWT using the HMAC-SHA256 signing standard, as shown in the following architecture diagram.

Architecture Diagram

Sample Toker Server Code

We have created a sample Token Server code (express-token-server) for use with local development testing and as the basis of a production deployment. Please reach out to our Support team (support@soulmachines.com) to request a copy of the sample code.

Express Token Server

The express-token-server sample code generates signed JWTs. To use the values provided by DDNA Studio, copy the .env.template file to .env, then within that copied file:

  1. Assign the SESSION_SERVER variable to the Session Server name provided by Studio.

  2. Assign the JWT_PUBLIC_KEY variable to the Key Name provided by Studio.

  3. Assign the JWT_PRIVATE_KEY variable to the Private Key provided by Studio.

React and Angular Templates

UI sample code in the form of React template can be used in conjunction with the express-token-server code for JWT generation.


Connect to a Custom Back-end

When utilizing a Token Server, if you intend to connect your Digital Person to a custom Orchestration Server, you must include the address of this server in your signed JWT using the sm-control field.

Refer to the Using Token Server for more information on configuring your JWT.