Soul Machines leverages JSON Web Tokens (JWTs) for establishing secure, unique sessions between your users and the Digital Person. Soul Machines provides template code upon request, written in Express (Node.js). This code generates and issues the necessary JWTs and passes it to Soul Machines servers (via Web SDK) for authentication. Any valid method of generating JWTs is supported—Soul Machines is agnostic to your backend language and framework.
Note that the issuer passes standard Soul Machines fields in the generated data packet, but you may create custom fields as well (important for scenarios requiring Orchestration). The finalized code for the token issuer must be hosted by the issuing organization (Soul Machines customer).
Standard JWT Fields
The following table describes the standard JWT fields.
Field
Description
sm-control
Your Orchestration Server URL, e.g. wss://example.com:8080
The sm-control field in your JWT is required to point to your Orchestration server. The Soul Machines video host uses this value to make an outbound WebSocket connection to the specified address.
It is also possible to make this a localhost address so you can just have a locally running Orchestration server which is useful for debugging, etc. To do this, you need to have the sm-control-via-browser flag set to "True" in the JWT, and the production flag set to "False" on the server.
Once the connection is established, messages flow back and forth over the WebSocket. The protocol for these messages is the same as the protocol which underlies the Web SDK, but some extra messages are permitted (mainly startSpeaking).
sm-session-server
The URL of the server where your Digital Person is hosted. For a Digital DNA Studio deployed Digital Person, you can find this URL on the Project Management page, under the Connection Config (Advanced) > Digital Person Server field. For customized environments, this is provided by your Soul Machines Solutions Architect. This is a mandatory field.
sm-control-via-browser
Flag to permit control via browser. Only allowed in Development environments.
sm-control-cookie-header
Field is set as Cookie header on the Orchestration server connection. This can be useful when working with components like load balancers which can act on headers.
iss
Issuer – the assigned ID for your JWT, e.g. “sm-abcdef123456789”
nbf
Not before timestamp. The time of issue with a small leeway for clock skew.
exp
Expires at timestamp.
iat
Issued at timestamp.
Custom JWT Fields
You may add any other fields you wish to your JWT, for example, a custom session ID, which is passed on to your backend Orchestration server. Custom JWT fields enable you to set up a shared state between your backend and your frontend.
Notes: You must avoid the sm- prefix in field names. To prevent tampering with the token, the JWT must be signed with your private key that was pre-shared with you by Soul Machines.