API Authentication - Generating JSON Web Tokens

Owned by Connor Montgomery (Deactivated)
Last updated: Sept 06, 2022 by Chitra Borker (Deactivated)
2 min read

Soul Machines leverages ​JSON Web Tokens​ (​JWT​s) 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.