Set up JWT Auth and Access Lucy API

Prerequisites

• Admin or SuperAdmin access to the Lucy instance
• Ability to generate and securely store JWT secrets (Symmetric or Asymmetric)
• Company ID (cid) provided by the Lucy team

Locate Your Lucy Instance ID

1. Login to the Lucy instance.
2. Navigate to Settings.
3. Note the Instance ID from the URL.

JWT Key Configuration

• Navigate to: Settings → Security → JWT Configuration → Add Secret Key
  View full size
• Click Add Secret Key
• Provide your JWT secret
• Choose Symmetric or Asymmetric
• Important: Once the key is added to Lucy or Answer Engine, it will not be visible again. Store it securely.
• If Auto provisioning is required, the under Manage Security Features section, Auto Provisioning toggle needs to be enabled
• If users need to be added in Auth0, then the under Manage Security Features section, Provisioning adds users to Auth0toggle needs to be enabled
  • Required if users expect to access Answer Engine webui in future

Symmetric Key Setup (Recommended for Testing)

1. Navigate to Settings → Security
2. Click Add Secret Key
3. Generate a UUID or a 30+ character string as the secret and store it securely
4. Do NOT enable the Asymmetric toggle
5. Use this key to generate JWT tokens (e.g., via jwt.io)
6. JWT Key generation format with example:

   Header:

   {
     "alg": "HS256",
     "typ": "JWT"
   }

   Payload Data:

   {
     "mode": "api",
     "firstname": "first_name",
     "lastname": "last_name",
     "email": "valid email id",
     "iat": 1752074171, ---- time in Unix Timestamp (Seconds): Refer https://www.epochconvert.com/
     "exp": 1752160571, ---- time in Unix Timestamp (Seconds): Refer https://www.epochconvert.com/
     "cid": "Lucy_instance_id"
   }

View full size

7. Delete this key from Lucy after testing is complete

Asymmetric Key Setup (Recommended for Production)

• Generate Key Pair

# Private Key
openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048


# Public Key
openssl rsa -pubout -in private_key.pem -out public_key.pem

• Only the key content (excluding -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----) should be added to Lucy.
• Navigate to Settings → Security
• Click Add Secret Key
• Mark as Asymmetric
• Paste only the content of public_key.pem (excluding headers/footers)

JWT Token Format

1. Header:

   {
     "alg": "RS256",
     "cid": "Lucy_instance_id"
   }

   Payload Data:

   {
     "mode": "api",
     "firstname": "first_name",
     "lastname": "last_name",
     "email": "valid email id",
     "iat": 1752074171, ---- time in Unix Timestamp (Seconds): Refer https://www.epochconvert.com/
     "exp": 1752160571 ---- time in Unix Timestamp (Seconds): Refer https://www.epochconvert.com/
   }

Authenticate in Lucy using JWT Token

• Once the JWT token is generated, use the token as Bearer token in the Header for the below Lucy Authentication API

• Request Payload 

  curl --location --request POST 'https://ask.lucy.ai/api/qna/start' \
  --header 'Authorization: Bearer JWT_Token'

  • Note: the base URL for all the API is https://ask.lucy.ai/api/qna or the customer specific {customized_url}/api/qna 

  • Postman request screenshot of Request and Response of Authentication (/start) API

    View full size

    
    

• Response

  • If successfully validated then the caller will simply receive the auth token as part of the response. The body itself will be a string object, that is the auth token. 
  • The auth token will be uses in further API calls such answer API, synopsis API etc
  • If the validation fails then the API will throw following errors-

Accessing Answers Endpoint (Request & response)

Request Payload

curl --location --request GET 'https://ask.lucy.ai/api/qna/answers?q={question/query}&source=lucy&selected_answers_limit=12&researchType=QnA&saveHistory=true&lucy-version=4&companyId={lucy_company_id}&synopsis=false' \
--header 'x-auth-token: {auth_token_returned_fron_start_API}'

• Please make sure to use the auth_token retrieved from /start API endpoint as header in the API request

Response

• Answers API will return set of answers along with other properties in JSON Format

• Here is response screen shot. Capture the value of qnaToken

  • 
    

    View full size

Accessing Synopsis Endpoint (Request & response)

Request Payload

curl --location --request GET 'https://ask.lucy.ai/api/qna/synopsis?q={question/query}&source=lucy&selected_answers_limit=12&researchType=QnA&saveHistory=true&lucy-version=4&companyId={lucy_company_id}&synopsis=false&qnaToken={token_from_answers_api}' \
--header 'x-auth-token: {auth_token_returned_fron_start_API}'

• Please make sure to pass retrieved qnaToken from answers API endpoint as query param in Synopsis API
• Please make sure to use the auth_token retrieved from /start API endpoint as header in the API request

Response

• Synopsis API endpoint will return the same answers for the question/query along with a property called shortAnswer which contains the Synopsis

• Here is the sample response

  View full size

Accessing Explore more questions Endpoint (Request & response)

Request Payload

curl --location --request POST 'https://ask.lucy.ai/api/qna/get-question-suggestions-to-explore' \
--header 'x-auth-token: {auth_token_returned_fron_start_API}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "content": "{shortAnswer_from_synopsis_api}",
    "numberOfQuestions": 3
}'

• Please make sure to use the auth_token retrieved from /start API endpoint as header in the API request
• payload should have below key value as raw data (JSON format)
  • content: shortAnswer_from_synopsis_api : STRING
  • numberOfQuestions : can be any number (ideally 10) : INETEGER

Response

• Explore more questions Endpoint will return number of questions based on the request payload as JSON array of strings

• Here is a sample response

View full size