Login & Authentication API

The Democrance platform has two classes of login. One for end customers (see customer login), and one for Users. Users generally belong to groups and can be admins, or service centre operators, claims team members or brokers.

Access to the Democrance back-end is optional for Users. Generally a user requires a username and password to log in, and can have additional attributes, such as a groups, a country, or a broker identifier.

Generally, when developing a custom client for Democrance, only brokers would use the user login to sell or administer insurance policies via the API.

User Login

URL	/api/v3/login/
Methods	POST

This endpoint can be called to authenticate and login a customer. Simply post the following data values when making a POST request to this end point:

{
    "username": "<Customer username>",
    "password": "<Customer password>"
}

Key	Description
username
password

Customer Login

Customer access and authentication is mobile phone centric. While policies can be retrieved without access to the phone, more advanced levels of authentication require that they are able to receive SMS messages to their phone.

Customers have two levels of login state. One is when a customer comes in from the web with a LEAD ID token without authentication and purchases a policy for themselves. A valid LEAD ID will pre-fill customer information on a policy application form.

Once they have purchased a policy, they will be entitled to access the certificate of insurance that they have purchased automatically.

Policies that have been purchased previously can be accessed one of two ways. In order to retrieve a copy of a previously purchased policy the customer needs to provide the policy number and their surname.

If they wish to view all the policies associated with their phone number, they need to complete a one time password process, where they submit their phone number and receive an SMS with a one time password. The authentication needs to be completed in a short time frame, before the session expires.

Once OTP authentication completes, the customer is able to view and update all of their details, retrieve past policies that they have purchased as well as initiate claims against these policies.

Customer Account Restore API

URL	/api/v3/login/customer/restore-account
Methods	POST

This endpoint helps customers restore their accounts by guiding them through a customized journey based on the product they use.

Here example for Valid form response related this endpoint.

Key	Type	Description
form	Dict	An object representing the form schema which needs to be completed. See ?? for details about form schemas.
has_errors	Boolean	A boolean flag to indicated if the form has an errors. This will be false if you are requesting the form.
next_action	String	The text that indicates what the next action in the journey is: continue, display (custom content), rejected, referred, complete, perform_otp.

The POST data should take the same shape as the form schema sent to you. You will need to include the validation previously supplied to continue submitting data.

Generating a One-Time Password (OTP)

One time passwords expire within 5 minutes of being issued.

URL	/api/v3/otp/
Methods	POST

To generate a One-Time Password (OTP) for an existing customer. Simply call this endpoint, posting the customer’s mobile phone in the POST payload as shown below. Currently OTP will require that the client maintains a cookie based session.

{
    "mobile": "+9711111111"
}

Note

The mobile number needs to be an exact match to the one we currently have for the customer, including the + prefix.

Regardless to if we manage to match a customer with a matching mobile number, you will always received the following response from the server:

{
    "status": "OK"
}

Note

The response is always ‘OK’ to prevent data mining attacks, in which an attack would attempt to mine valid mobile numbers from our API.

Using One-Time Password (OTP)

URL	/api/v3/check-otp/
Methods	POST

OTP login expects the following body along with the session cookie:

{
    "otp": "123456"
}

Valid responses are:

{
    "status": "Logged In",
    "customer_login_token": ""
}

Key	Description
status	One of: ‘Logged In’, ‘Login Failed’
customer_login_token

Using a lead

A successful lead login will allow a user to make use of the customer API __ADD_LINK__ call to retrieve limited customer details that we have stored on our system, which can be used to pre-fill a policy purchase form.

The lead login will return the subproduct a lead was created for, as well as registering that the customer has clicked a link with the lead id, and moves them forward in the campaign state from ‘NEW’ to ‘POTENTIAL’. __ADD_LINK__

URL	/api/v3/login/lead/
Methods	POST

{
    "lead_id": "abcdef"
}

Key	Type	Description
lead_id	String	The unique lead identifier for a customer who is registered on the Democrance platform.

On a successful login, the server will respond with the following:

{
    "subproduct_slug": "subproduct_a",
    "product_slug": "product_1"
}

Key	Type	Description
product_slug	String	The product for which the lead was intended for
subproduct_slug	String

The subproduct_slug can then be used to direct the customer to the specific subproduct registered with the campaign.

Logging out

URL	/api/v3/logout/
Methods	GET, POST

To end a customer/user session, simply call this endpoint. The request can be either GET or POST, and will result in the current session being ended, and the following response sent back to you.

{
    "status": "OK"
}

Initiating a session

URL	/api/v3/init/
Methods	GET

Calling this endpoint will provide you with a session and CRSF tokens, to be used with future communications with the server. CSRF and Session tokens can be passed as headers with requests using x-session-id and x-csrftoken headers respectively.

The server will respond with the following:

{
    "csrf_token": "lqqASSUzT6xJsyUOgT3Av3lrhsB8Sm9J",
    "login_type": "user",
    "session_id": "xxxx"
}

Key	Description
csrf_token	CSRF token, used for web based clients only. Not required for mobile scenarios.
login_type	Can be one of ‘user’ or ‘customer’ depending on whether a broker or an end customer is logging in
session_id	A string identifying the current session, that can be used with clients that don’t have cookies.

Login API (Without Two Factor Authentication)

URL	/api/v3/login/
Methods	POST

Login expects the following body:

{
    "username": "test_user"
    "password": "123456"
}

Key	Type	Description
username	String	Username - case sensitive
password	String	Password

Valid responses are:

{
    "status": "Logged In",
    "country": "AE",
    "roles": [
        "underwriter"
    ],
    "org": "XYZ Agency"
}

Key	Type	Description
status	String	One of: ‘Logged In’, ‘Login Failed’
country	String	User’s extension country short code
roles	List	List of all groups user belongs to.
org	String	Organization name user belongs.

Login API (With Two Factor Authentication)

URL	/api/v3/login/
Methods	POST

Login expects the following body:

{
    "username": "test_user"
    "password": "123456",
    "auth_session_key": "hash_key"
}

Key	Type	Description
username	String	Username - case sensitive
password	String	Password
auth_session_key	String	Generated key from Democrance’s Backend. To be stored to keep the session alive.

Valid responses are (if the hash_key is a valid one or not empty):

{
    "success": true,
    "action": "Logged in",
    "message": "User has successfully logged In.",
    "status": "Logged in",
    "country": "AE",
    "roles": [
        "underwriter"
    ],
    "org": {
        "XYZ Agency": [
            "Username1",
            "Username2"
        ]
    },
    "auth_session_key": "hash_key"
}

Key	Type	Description
success	Boolean	Request processed successfully or not.
action	String	One of: ‘Logged In’, ‘Login Failed’, ‘Authentication Required’
status	String	One of: ‘Logged In’, ‘Login Failed’, ‘Authentication Required’
country	String	User’s extension country short code
roles	List	List of all groups user belongs to.
org	List	List of all organizations user belongs.
auth_session_key	String	Generated key from Democrance’s Backend. To be stored to keep the session alive.
message	String	Display message from server side.

Valid responses are (if the hash_key not a valid one or empty):

{
    "action": "Authentication Required",
    "message": "To help validate the process, a One-Time Password (OTP) has been sent to your email/sms",
    "status": "Authentication Required"
}

Key	Type	Description
action	String	One of: ‘Logged In’, ‘Login Failed’
message	String	Display message from server side.
status	String	One of: ‘Logged In’, ‘Login Failed’

Validating Login OTP expects the following body:

{
    "auth_otp": "123456"
}

Key	Type	Description
auth_otp	String	OTP to verify the user login.

Valid response:

{
    "success": true,
    "action": "Logged in",
    "message": "User has successfully logged In.",
    "status": "Logged in",
    "country": "UAE",
    "roles": [
        "underwriter"
    ],
    "org": {
        "XYZ Agency": [
            "Username1",
            "Username2"
        ]
    },
    "auth_session_key": "hash_key"
}

Key	Type	Description
success	Boolean	Request processed successfully or not.
action	String	One of: ‘Logged In’, ‘Login Failed’, ‘Authentication Required’
status	String	One of: ‘Logged In’, ‘Login Failed’, ‘Authentication Required’
country	String	User’s extension country short code
roles	List	List of all groups user belongs to.
org	List	List of all organizations user belongs.
auth_session_key	String	Generated key from Democrance’s Backend. To be stored to keep the session alive.
message	String	Display message from server side.