Login

Description

This service logs a party into Thalamus by authenticating their credentials.

🔑 A Note on Authentication: Thalamus uses BASIC AUTH for managing the session. Your client application should be configured to handle this.

The primary user identifier depends on the specific Thalamus instance configuration. Before development, you must confirm which of the following is used:

• Username

• Email

• Document (Type + Number)

• A custom principal

Additionally, some touchpoints may be configured for passwordless login (e.g., for kiosk applications used by promoters). In these cases, the password field is not required, but the service functions identically otherwise.

---

Request

Restrictions

This service can only be called when the party is not already logged in.

Endpoint

POST https://<server-url>/api/v4/signin

Parameters

Parameter	Location	Description
touchpoint	Query / Header	The identifier for the touchpoint. Use Thalamus-Touchpoint for the header.
token	Query / Header	The authentication token for the API. Use Thalamus-Token for the header.
activity	Query / Header	Optional. The activity to be used. Use Thalamus-Activity for the header.
Content-Type	Header	Specifies the content type of the request body. Must be application/json.

Full URL Example

https://<server-url>/api/v4/signin?touchpoint=test&token=...

Request Body

The request body contains the user's credentials.

Field	Type	Description
principal	String	The user's primary identifier. The format depends on the instance configuration (see table below).
password	String	The user's password (4-100 characters). May not be required for certain touchpoints.

Principal Formats

Identifier Type	Format	Example
Username or Email	[email protected]	"principal": "[email protected]"
Document	documentTypeId:documentNumber	"principal": "1:27564734"
Document (for Basic Auth)	documentTypeId$documentNumber	"principal": "1$27564734"
Cellphone	intCode-areaCode-number	"principal": "54-11-30740001"
Composite ID	fieldCode_idValue_fieldValue	"principal": "compositeField_id0_value123xyz"

JSON

{
  "principal": "[email protected]",
  "password": "user_password"
}

---

Response

✅ Successful Response: 200 OK

A successful login returns a 200 OK status and sets the necessary session cookies in the response headers. The response body will contain the user's session context, including profile information and available activities.

❌ Unsuccessful Response: 401 Unauthorized

Returned if the user is not permitted to log in under the current circumstances.

Scenario: Invalid Credentials

JSON

{
  "errors": {
    "error.message": "UNAUTHORIZED",
    "error.code": "401",
    "error.description": "Wrong credentials."
  }
}

Scenario: Insufficient Identity Validation Level

This occurs when a user's account has not been fully verified and the touchpoint requires a higher level of validation.

JSON

{
  "errors": {
    "error.message": "UNAUTHORIZED",
    "error.code": "401",
    "error.description": "User is disabled"
  }
}

Scenario: Insufficient Identity Validation Level (Error Version 2)

If using ev=2, the error message will be more specific.

JSON

{
  "errors": {
    "code": "UNDER_VALIDATION",
    "message": "Person with identity UNDER_VALIDATION cannot login in this touchpoint"
  }
}

❌ Unsuccessful Response: 404 Not Found

Returned if the provided principal does not exist in the system.

For touchpoints that do not require a password, a 404 response indicates that the user should be prompted to register.

JSON

{
  "errors": {
    "error.message": "NOT_FOUND",
    "error.code": "404"
  }
}