Soul Machines leverages JSON Web Tokens (JWTs) for establishing secure, unique sessions between your users and the Digital Hero. 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 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-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 back end and your front end.
NOTES: You must avoid the sm- prefix on 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.