Build Your Own experience

Obtaining an access token

5min

In order to initiate a conversation session with a Digital Human, your application must first acquire a one time use access token to be used by your website and the uneeq-js SDK to authenticate to the UneeQ Platform.
﻿
Example App
Check out this example Node application which returns a single use token as generated by the UneeQ API server.
﻿
Customer JWT token
The process to acquire a one time use token requires JWT encryption (on the client side), and JWT decryption (on the UneeQ server). To achieve this, a shared JWT secret must be possessed by both sides. This JWT secret can be retrieved from the Deploy > Build your own area of UneeQ Creator. Otherwise, our Customer Success team can provide you with this token. Clients may not provide their own.
﻿
Connection URL
Region
Connection URL
North America
https://api.us.uneeq.io
Europe
https://api.eu.uneeq.io
Oceania
https://api.au.uneeq.io
﻿
Request specification
Get a single use session token
POST
Request
Header Parameters
content-type
required
String
"application/jwt"
workspace
required
String
The workspaceId is the ID which identifies the Persona that you wish to start a conversation with. You can find your personaId within the Personas area of the UneeQ Creator. Otherwise, our Customer Success team can provide you with this ID.
Body Parameters
JWT Signed Request
required
String
JWT token request signed with the customers secret. The token request should have following fields:
"sid": string
"fm-workspace": string // persona id
"fm-custom-data": string // stringified JSON
Node.js
Python
Ruby
require 'jwt'
include HTTParty

# This example initializes global variables with static values, in a real implementation, you should use environment variables passed into your application.
# Never hardcode any sensitive credentials into a production application.
# You will need to merge the sample code below into a proper Ruby Class or if you are using Ruby on Rails, an appropriate Rails location such as a controller
$persona_id = '035c9044-f655-11ec-b939-0242ac12000' # Replace value with your Persona ID from within UneeQ Creator
$api_endpoint_url = 'https://api.us.uneeq.io' # Replace with other region if your account is provisioned outside the US
$customer_jwt_secret = '035c9044-f655-11ec-b939-0242ac12000' # Replace value with your JWT Secret, which you can find within your UneeQ Creator portal

def authenticate_to_uneeq
    response = HTTParty.post(
            "#{$api_endpoint_url}/api/v1/clients/access/tokens",
            headers: { "Content-Type": 'application/jwt', "workspace": $persona_id },
            body: encode_payload
        )

    return response
end

def encode_payload
    payload = {
      'sid' => 'RANDOM SESSION ID VALUE', 
      'fm-custom-data' => JSON.generate({}), # Put whatever key-value pairs you'd like and they will be returned from UneeQ on each request to your NLP layer in fm-custom-data
      'fm-workspace' => $persona_id
    }

    token = JWT.encode payload, $customer_jwt_secret, 'HS256'
end
require 'jwt'
include HTTParty

# This example initializes global variables with static values, in a real implementation, you should use environment variables passed into your application.
# Never hardcode any sensitive credentials into a production application.
# You will need to merge the sample code below into a proper Ruby Class or if you are using Ruby on Rails, an appropriate Rails location such as a controller
$persona_id = '035c9044-f655-11ec-b939-0242ac12000' # Replace value with your Persona ID from within UneeQ Creator
$api_endpoint_url = 'https://api.us.uneeq.io' # Replace with other region if your account is provisioned outside the US
$customer_jwt_secret = '035c9044-f655-11ec-b939-0242ac12000' # Replace value with your JWT Secret, which you can find within your UneeQ Creator portal

def authenticate_to_uneeq
    response = HTTParty.post(
            "#{$api_endpoint_url}/api/v1/clients/access/tokens",
            headers: { "Content-Type": 'application/jwt', "workspace": $persona_id },
            body: encode_payload
        )

    return response
end

def encode_payload
    payload = {
      'sid' => 'RANDOM SESSION ID VALUE', 
      'fm-custom-data' => JSON.generate({}), # Put whatever key-value pairs you'd like and they will be returned from UneeQ on each request to your NLP layer in fm-custom-data
      'fm-workspace' => $persona_id
    }

    token = JWT.encode payload, $customer_jwt_secret, 'HS256'
end
Responses
200
400
401
403
500
{
  "token": "035c9044-f655-11ec-b939-0242ac120002" // A single-use token as a UUID will be returned
}
{
  "token": "035c9044-f655-11ec-b939-0242ac120002" // A single-use token as a UUID will be returned
}
﻿
The token value can then be used by the uneeq-js SDK to instantiate a conversation session with a digital human via initWithToken() method. SDK Methods﻿﻿
﻿
Request Body Details
This payload should be encrypted using the customerUneeqSecret:
Field
Type
Description
sid
String
A value defined by you, to help you identify this conversation session in your own platform. Can be a blank string.
fm-custom-data
String
Optional. Any ad-hoc values you wish to be sent in any subsequent  from the Platform. Must be stringified JSON.
fm-workspace
String
The workspaceId is the ID which identifies the Persona that you wish to start a conversation with. You can find your personaId within the Personas area of the . Otherwise, our Customer Success team can provide you with this ID.
Node.js
Python
Ruby
import jwt

jwt_secret = 'YOUR JWT SECRET FROM WITHIN CREATOR'

message = {
        'sid': 'SESSION-ID', # Can be any value you wish
        'fm-workspace': personaId,
        'fm-custom-data': json.dumps({}) # You can pass custom key-value pairs here, they will be returned from UneeQ as fm-custom-data
    }

compact_jws = jwt.encode(message, jwt_secret, algorithm='HS256')
import jwt

jwt_secret = 'YOUR JWT SECRET FROM WITHIN CREATOR'

message = {
        'sid': 'SESSION-ID', # Can be any value you wish
        'fm-workspace': personaId,
        'fm-custom-data': json.dumps({}) # You can pass custom key-value pairs here, they will be returned from UneeQ as fm-custom-data
    }

compact_jws = jwt.encode(message, jwt_secret, algorithm='HS256')
﻿
﻿

Region	Connection URL
North America	https://api.us.uneeq.io
Europe	https://api.eu.uneeq.io
Oceania	https://api.au.uneeq.io

Field	Type	Description
sid	String	A value defined by you, to help you identify this conversation session in your own platform. Can be a blank string.
fm-custom-data	String	Optional. Any ad-hoc values you wish to be sent in any subsequent from the Platform. Must be stringified JSON.
fm-workspace	String	The workspaceId is the ID which identifies the Persona that you wish to start a conversation with. You can find your personaId within the Personas area of the . Otherwise, our Customer Success team can provide you with this ID.

SDK Messages

Conversation platform integrations