Quick facts
Some information on persons and their login
- Each person can have exactly one username (alpha-numeric) and password (alpha-numeric)
- Passwords are never stored as plain-text within Hublify
- Hublify supports temporary suspending of existing logins
- Hublify supports password-forgotten mechanism
- Hublify supports one-login-tokens (with time-out function)
Prerequisites
You should have
- an user-account enabled for api access & PIM access
- an api-client
- at least one person-record stored in your Hublify CRM
Setting a new password
In order to update a person's password, you simply use the standard data-update endpoint.
If the new password does not meet the configured complexity-requirements the complete update request ist not executed.
Request URL
https://{your hublify url}/api/eos_10/data_update
Request parameter
{
"dataset": "person",
"fields": {
"p_login_pwd_plain": "<new password>"
},
"filter": {
"personid": "<PersonId>" //
}
}
Response
{
"status": true
}
Getting a person's password
"Sorry"! There is for security reasons no possibility to get a persons password! Neither for you nor for Hublify employees.
Checking password-strength
You can do live checks on the quality of a provided plain-text password.
Use this endpoint if want to check before executing a data_create or data_update for a person-record if the new password would fulfill the password requirements.
Request URL
https://{your hublify url}/api/eos_10/person_getPasswordQuality
Request parameter
{
"password": "<the plain-text password>"
}
Response
{
"status": true, // TRUE if password is sufficient
"msg": [ ... ] // In case of error, here are i18n-messages provided.
}
Login: Authenticate a person
You can use a special endpoint in the functional api to perform a Hublify-based login for person in your Hublify CRM.
Using this endpoint includes following actions and events
- Checks for existing username
- Compares with encrypted stored password
- Sets the "last-login-time" in person-record
- [ Trigger automatic on-login processes ]
SECURITY: Be sure to have SSL especially on this api request enabled (... as actually for all other requests as well).
Request URL
https://{your hublify url}/api/eos_10/person_login
Request parameter
{
"username": "<username>",
"password": "<plain-text password>", // The plain-text-password that the user entered for login.
// This can be also be a previously created one-time-password.
// !!! BE SURE to call the api always with SSL !!!
"authcode": "<previously sent>", // The "2FA-Code" (commonly like 6-digit code).
"login_token": "<previously sent>", // Direct-Login Token (commonly 32-64 chars)
"fields": [ // (optional) Define what fields you want to have directly returned on successful login
"personid", "firstname", "lastname"
]
}
Response
{
"status": true, // TRUE: Login successful, else login failed.
"meta": {
"loginState": "<code>", // Can be either: "ok|error|suspended|disabled|confirmauthcode"
"loginType": "<code>", // Can be either: "pwd|otpwd|token|2fa|NULL"
// This is, how the person logged in.
"loginSuspendTime": "<dateTime>", // If not NULL it contains the next possible login-time. Until then it is blocked.
"pwdMustRenew": true, // boolean (optional, default NULL/ FALSE). If TRUE the login-frontend shall force
// the user to enter a new password. Either because
// a) ...the password timedout
// b) ...he logged in via "login_token" ("pwd forgotten proc")
}
"data": {
"personid": "<...>", // The optionally requested fields
"firstname": "<...>",
"lastname": "<...>"
}
}
Results
status : TRUE - Login was successful. FALSE if the login failed.
Be sure to evaluate also: [meta][loginState] !
Possible login failure reasons are:
- unknown username / wrong password
(There is explicitly no distinction made, for security reasons)
- login temporarily suspended
(Username correct, Password not checked)
Logout
Request URL
https://{your hublify url}/api/eos_10/person_logout
Request parameter
{
"username": "<username>",
}
person_login_send2FA
Looks up the person-record and usually sends an email with instantly created 2FA-Code.
Request URL
https://{your hublify url}/api/eos_10/person_login_send2FA
Request parameter
{ "username": "<username>",
}
person_login_sendToken
Looks up the person-record and usually sends an email with the direct-login-link.
Request URL
https://{your hublify url}/api/eos_10/person_login_sendToken
Request parameter
{ "username": "<username>",
}