User authentication and sign-in

curl --request POST \
  --url https://hiimpria.ai/api/auth/signin \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "john.doe@mydomain.com",
  "password": "iLovePria123"
}
'

import requests

url = "https://hiimpria.ai/api/auth/signin"

payload = {
    "email": "john.doe@mydomain.com",
    "password": "iLovePria123"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({email: 'john.doe@mydomain.com', password: 'iLovePria123'})
};

fetch('https://hiimpria.ai/api/auth/signin', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://hiimpria.ai/api/auth/signin",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'email' => 'john.doe@mydomain.com',
    'password' => 'iLovePria123'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://hiimpria.ai/api/auth/signin"

	payload := strings.NewReader("{\n  \"email\": \"john.doe@mydomain.com\",\n  \"password\": \"iLovePria123\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://hiimpria.ai/api/auth/signin")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"john.doe@mydomain.com\",\n  \"password\": \"iLovePria123\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://hiimpria.ai/api/auth/signin")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"john.doe@mydomain.com\",\n  \"password\": \"iLovePria123\"\n}"

response = http.request(request)
puts response.read_body

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI2NDMwNzM2ZmQ2MmQ2NTAwNDA0MjA2NzQiLCJlbWFpbCI6ImpvaG4uZG9lQG15ZG9tYWluLmNvbSIsImN1c3RvbWVySWQiOiJjdXNfTnh4eHh4eCIsImFjY291bnRUeXBlIjoidXNlciIsInNlc3Npb25JZCI6InMlM0FhYmMxMjMiLCJpYXQiOjE3MDAwMDAwMDAsImV4cCI6MTcwMDA4NjQwMH0.signature",
  "profile": {
    "_id": "<string>",
    "email": "jsmith@example.com",
    "fname": "<string>",
    "lname": "<string>",
    "picture": "<string>",
    "accountType": "<string>",
    "permissions": [
      "<string>"
    ],
    "customerId": "<string>",
    "lxp_user_id": "<string>",
    "lxp_user_type": 123,
    "lxp_partner_id": "<string>",
    "lxp_partner_name": "<string>",
    "lxp_role_id": 123,
    "lxp_role_name": "<string>",
    "credits": 123,
    "creditsUsed": 123,
    "plan": "<string>",
    "status": "<string>",
    "trial_end": "2023-11-07T05:31:56Z",
    "trial_used": true,
    "current_period_end": "2023-11-07T05:31:56Z",
    "cancel_at_period_end": true,
    "referralId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "referrerPaid": true,
    "resetCodeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "invoices_urls": [
      "<string>"
    ],
    "remember_history_count": 123,
    "browser_voice": "<string>",
    "rt_voice": "<string>",
    "use_location": true,
    "showSideBar": true,
    "dark_mode": true,
    "created": "2023-11-07T05:31:56Z",
    "__v": 123,
    "institution": {
      "_id": "<string>",
      "name": "<string>",
      "picture": "<string>",
      "picture_bg": "<string>",
      "picture_dark_bg": "<string>",
      "picture_animated": "<string>",
      "elevenlabs_agent_id": "<string>",
      "credits": 123,
      "status": "<string>",
      "allowJoining": "<string>",
      "joiningAdminOnly": true,
      "publicId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "publicAuthorizedUrls": [
        "<string>"
      ],
      "ainame": "<string>",
      "contactEmail": "jsmith@example.com",
      "creditAward": 123,
      "poolCredits": true,
      "invoices_urls": [
        "<string>"
      ],
      "maxCompletionTokens": 123,
      "disableFileUploadForUser": true,
      "disableAudioNotesForUser": true,
      "toolsDisabled": [
        "<string>"
      ],
      "ltiContextIds": [
        "<string>"
      ],
      "personalisationAsked": true,
      "locationEnabled": true,
      "rtEnabled": true,
      "rtAdminOnly": true,
      "displayAgentDetails": true,
      "displayThinkingDetails": true,
      "displayRagSearchDetails": true,
      "displayMemoryDetails": true,
      "displayThinkingExecution": true,
      "displayToolExecution": true,
      "assistantsDisabled": [
        "<string>"
      ],
      "disableAssistantsForUser": true,
      "rtVoice": "<string>",
      "maxFiles": 123,
      "questionType": "<string>",
      "creditsTotal": 123,
      "creditsUsagePct": 123,
      "id": "<string>",
      "account": {
        "_id": "<string>",
        "name": "<string>",
        "status": "<string>",
        "canvasCredsResolved": true,
        "privacyPolicyHTML": "<string>",
        "privacyPolicyUpdatedAt": "2023-11-07T05:31:56Z",
        "privacyPolicyHash": "3bfb489f9bd077f0"
      }
    }
  },
  "brandingSwitch": {
    "publicId": "f831501f-b645-481a-9cbb-331509aaf8c1",
    "result": "switched",
    "reason": "<string>"
  },
  "mfaRequired": true,
  "challengeId": "6856fa89cbafcff8d98680f5",
  "maskedEmail": "j*****e@example.com",
  "codeSent": false,
  "stepUp": true
}

{
  "message": "Please enter a valid email address",
  "success": false
}

{
  "message": "Invalid Password !",
  "token": null
}

{
  "message": "Check your email for a one-time activation link to complete your account setup."
}

{
  "success": false,
  "code": "BAD_REQUEST",
  "message": "<string>",
  "attemptsRemaining": 4,
  "retryAfter": 24,
  "serverTime": 1790000000
}

{
  "success": false,
  "message": "The system can not sign you in at this time."
}

Authentication

User authentication and sign-in

Authenticates a user with email and password, and returns a JWT token along with the user profile. The profile carries passwordChangeRequired: whether THIS sign-in must land on the Change Password screen (mustChangePassword combined with the sign-in method: a password sign-in prompts, a Google/Microsoft/Facebook/Apple/LMS sign-in does not while passwordChangeSkipOnSSO is on).

Rate Limiting: 10 requests per minute per IP address.

JWT Token Lifecycle

On successful authentication, the response includes a token field containing a signed JWT.

Token payload:

_id — User’s unique identifier
email — User’s email address
customerId — Stripe customer ID (if applicable)
accountType — admin or user
sessionId — Server-side session identifier
iat — Issued-at timestamp (set automatically by JWT)
exp — Expiration timestamp (set automatically by JWT)

Token expiration: 6 hours (21,600 seconds) by default. Configurable via JWT_VALIDITY_SEC environment variable.

Using the Token

Include the JWT in every subsequent API request using one of these methods (in priority order):

x-access-token header (recommended):

x-access-token: eyJhbGciOiJIUzI1NiIs...

Authorization header with Bearer scheme:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Query parameter:

GET /api/resource?token=eyJhbGciOiJIUzI1NiIs...

Request body field:
{ "token": "eyJhbGciOiJIUzI1NiIs..." }

Token Errors

When a token is missing, expired, or invalid, the API returns:

403 — No token provided (Authentication Required)
401 — Token expired (jwt expired) or token invalid (invalid signature)

Token Renewal (Sliding Session)

Tokens are automatically refreshed via a sliding session mechanism. Each time the client calls POST /api/user/refresh/profile, the response includes a fresh JWT token with a new expiration. This extends the session without requiring re-authentication, as long as the current token is still valid.

The frontend calls this endpoint on every page load, so active users never experience token expiration. If the token expires (e.g., user is inactive for more than 6 hours), a new sign-in is required.

POST

api

auth

signin

User authentication and sign-in

curl --request POST \
  --url https://hiimpria.ai/api/auth/signin \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "john.doe@mydomain.com",
  "password": "iLovePria123"
}
'

import requests

url = "https://hiimpria.ai/api/auth/signin"

payload = {
    "email": "john.doe@mydomain.com",
    "password": "iLovePria123"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({email: 'john.doe@mydomain.com', password: 'iLovePria123'})
};

fetch('https://hiimpria.ai/api/auth/signin', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://hiimpria.ai/api/auth/signin",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'email' => 'john.doe@mydomain.com',
    'password' => 'iLovePria123'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://hiimpria.ai/api/auth/signin"

	payload := strings.NewReader("{\n  \"email\": \"john.doe@mydomain.com\",\n  \"password\": \"iLovePria123\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://hiimpria.ai/api/auth/signin")
  .header("Content-Type", "application/json")
  .body("{\n  \"email\": \"john.doe@mydomain.com\",\n  \"password\": \"iLovePria123\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://hiimpria.ai/api/auth/signin")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"email\": \"john.doe@mydomain.com\",\n  \"password\": \"iLovePria123\"\n}"

response = http.request(request)
puts response.read_body

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI2NDMwNzM2ZmQ2MmQ2NTAwNDA0MjA2NzQiLCJlbWFpbCI6ImpvaG4uZG9lQG15ZG9tYWluLmNvbSIsImN1c3RvbWVySWQiOiJjdXNfTnh4eHh4eCIsImFjY291bnRUeXBlIjoidXNlciIsInNlc3Npb25JZCI6InMlM0FhYmMxMjMiLCJpYXQiOjE3MDAwMDAwMDAsImV4cCI6MTcwMDA4NjQwMH0.signature",
  "profile": {
    "_id": "<string>",
    "email": "jsmith@example.com",
    "fname": "<string>",
    "lname": "<string>",
    "picture": "<string>",
    "accountType": "<string>",
    "permissions": [
      "<string>"
    ],
    "customerId": "<string>",
    "lxp_user_id": "<string>",
    "lxp_user_type": 123,
    "lxp_partner_id": "<string>",
    "lxp_partner_name": "<string>",
    "lxp_role_id": 123,
    "lxp_role_name": "<string>",
    "credits": 123,
    "creditsUsed": 123,
    "plan": "<string>",
    "status": "<string>",
    "trial_end": "2023-11-07T05:31:56Z",
    "trial_used": true,
    "current_period_end": "2023-11-07T05:31:56Z",
    "cancel_at_period_end": true,
    "referralId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "referrerPaid": true,
    "resetCodeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "invoices_urls": [
      "<string>"
    ],
    "remember_history_count": 123,
    "browser_voice": "<string>",
    "rt_voice": "<string>",
    "use_location": true,
    "showSideBar": true,
    "dark_mode": true,
    "created": "2023-11-07T05:31:56Z",
    "__v": 123,
    "institution": {
      "_id": "<string>",
      "name": "<string>",
      "picture": "<string>",
      "picture_bg": "<string>",
      "picture_dark_bg": "<string>",
      "picture_animated": "<string>",
      "elevenlabs_agent_id": "<string>",
      "credits": 123,
      "status": "<string>",
      "allowJoining": "<string>",
      "joiningAdminOnly": true,
      "publicId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "publicAuthorizedUrls": [
        "<string>"
      ],
      "ainame": "<string>",
      "contactEmail": "jsmith@example.com",
      "creditAward": 123,
      "poolCredits": true,
      "invoices_urls": [
        "<string>"
      ],
      "maxCompletionTokens": 123,
      "disableFileUploadForUser": true,
      "disableAudioNotesForUser": true,
      "toolsDisabled": [
        "<string>"
      ],
      "ltiContextIds": [
        "<string>"
      ],
      "personalisationAsked": true,
      "locationEnabled": true,
      "rtEnabled": true,
      "rtAdminOnly": true,
      "displayAgentDetails": true,
      "displayThinkingDetails": true,
      "displayRagSearchDetails": true,
      "displayMemoryDetails": true,
      "displayThinkingExecution": true,
      "displayToolExecution": true,
      "assistantsDisabled": [
        "<string>"
      ],
      "disableAssistantsForUser": true,
      "rtVoice": "<string>",
      "maxFiles": 123,
      "questionType": "<string>",
      "creditsTotal": 123,
      "creditsUsagePct": 123,
      "id": "<string>",
      "account": {
        "_id": "<string>",
        "name": "<string>",
        "status": "<string>",
        "canvasCredsResolved": true,
        "privacyPolicyHTML": "<string>",
        "privacyPolicyUpdatedAt": "2023-11-07T05:31:56Z",
        "privacyPolicyHash": "3bfb489f9bd077f0"
      }
    }
  },
  "brandingSwitch": {
    "publicId": "f831501f-b645-481a-9cbb-331509aaf8c1",
    "result": "switched",
    "reason": "<string>"
  },
  "mfaRequired": true,
  "challengeId": "6856fa89cbafcff8d98680f5",
  "maskedEmail": "j*****e@example.com",
  "codeSent": false,
  "stepUp": true
}

{
  "message": "Please enter a valid email address",
  "success": false
}

{
  "message": "Invalid Password !",
  "token": null
}

{
  "message": "Check your email for a one-time activation link to complete your account setup."
}

{
  "success": false,
  "code": "BAD_REQUEST",
  "message": "<string>",
  "attemptsRemaining": 4,
  "retryAfter": 24,
  "serverTime": 1790000000
}

{
  "success": false,
  "message": "The system can not sign you in at this time."
}

Body

application/json

string<email>

required

Example:

"john.doe@mydomain.com"

password

string<password>

required

Example:

"iLovePria123"

Response

Successful authentication. Returns JWT token and user profile.

Successful signin response shape. Two variants are returned by the same endpoint depending on whether email MFA is required: • JWT issued — { token, profile }. The user is signed in. • MFA challenge — { mfaRequired: true, challengeId, maskedEmail, codeSent?, stepUp? }. The client must POST the 6-digit code to /api/auth/mfa-verify with the challengeId; the verify endpoint then issues the JWT. Discriminate via mfaRequired === true (per Phase 1 design §6.1).

token

string

Signed JWT token. Present when MFA is not required or has just been verified. Include this in subsequent API requests via the x-access-token header or Authorization Bearer header. Expires after 6 hours (configurable via JWT_VALIDITY_SEC). Automatically refreshed on profile load (sliding session).

Example:

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI2NDMwNzM2ZmQ2MmQ2NTAwNDA0MjA2NzQiLCJlbWFpbCI6ImpvaG4uZG9lQG15ZG9tYWluLmNvbSIsImN1c3RvbWVySWQiOiJjdXNfTnh4eHh4eCIsImFjY291bnRUeXBlIjoidXNlciIsInNlc3Npb25JZCI6InMlM0FhYmMxMjMiLCJpYXQiOjE3MDAwMDAwMDAsImV4cCI6MTcwMDA4NjQwMH0.signature"

profile

object

Show child attributes

brandingSwitch

object

Outcome of a branded-link switch attempt. Present only when the request carried a brandingId (an institution publicId from a /login?brandingId= link). The hint never grants access: switched requires an active membership on the twin (or platform-operator status) and an active parent account. Clients clear the stored hint on switched/already and show the no-access notice on refused.

Show child attributes

mfaRequired

boolean

When true, the response is an MFA challenge — no JWT issued. Client should redirect to the MFA verify screen with the challengeId.

Example:

true

challengeId

string

MongoDB ObjectId of the issued mfaChallenge. Only present when mfaRequired: true. POST this to /api/auth/mfa-verify alongside the 6-digit code.

Example:

"6856fa89cbafcff8d98680f5"

maskedEmail

string

Partially-masked email address the verification code was sent to (for the verify-screen "code sent to …" prompt). Only present when mfaRequired: true.

Example:

"j*****e@example.com"

codeSent

boolean

false when the challenge comes from an SDK / Canvas launch (/api/auth/autosignup with institution_id or lticontextid): no code has been emailed yet. Show a "Send me a code" action that calls /api/auth/mfa-resend (the first send is not subject to the 30-second wait), then the code entry. A repeated launch of the same Digital Twin and course from the same network within the challenge's lifetime answers with the same challengeId, so a code already emailed keeps working; a launch of another Digital Twin or course, or from another network, gets its own challenge (a network keeps at most three pending launch challenges of a person — a fourth replaces the oldest). Absent or true means the code was emailed.

Example:

false

stepUp

boolean

true when the sign-in asks for a code before any session is opened — an embedded / Canvas launch, or a provider sign-in, of an account that needs a second proof first. Comes with codeSent: false: show "Send me a code" (/api/auth/mfa-resend), then the code entry; /api/auth/mfa-verify then signs the person in — on a launch, to the launched Digital Twin and course. Absent or false otherwise.

Example:

true

Overview

Getting Started

LMS Integrations

Voice & Avatars

Web & Chat Integrations

MCP Server

JavaScript SDK

Authentication

REST API

Runtime API

Administrator API

User authentication and sign-in

JWT Token Lifecycle

Using the Token

Token Errors

Token Renewal (Sliding Session)

Body

Response