Logging users in
- Call name: login
- Endpoint URL: https://api0.spaaza.com/auth/login
- Request methods: POST
- Request Content-Type: multipart/form-data or application/x-www-form-urlencoded
- Response Content-Type: application/json
- Auth required: no
When supplied with a username and password, this API checks whether the password is valid for the username. If it is valid, it deletes any existing sessions, and then creates a session with a session key in the database. It then returns session information in JSON. Note that the session_expires_date is returned in UTC date time format. If the user is an admin user, Two-Factor Authentication (2FA) is enabled, which means that the API will return a session passcode key and the user will be emailed a session passcode. The user must then use the session passcode and session passcode key to obtain a session via the session endpoint. If the admin user is exempt from 2FA (login_2fa_exempt is true), the login response returns session_info and user_info directly, like a normal login.
Version-specific information
The following version-specific changes apply to this endpoint. See the versioning page for more details.
| Version | Change details |
|---|---|
| >= 1.5.8 | For admin user login, Two-Factor Authentication is introduced, meaning a login request returns a session passcode key and the user will be emailed a session passcode. Admin users marked as login_2fa_exempt skip 2FA and receive session_info and user_info directly in the login response. |
| >= 1.4.10 | The gender parameter returned in the user_info object supports values male, female, nonbinary, transgender, agender, genderqueer, genderfluid, bigender, twospirit, androgynous, pangender, neutrois, demigender and other. |
HTTP Parameters
The following HTTP POST parameters can be passed to the API:
| Parameter | Description |
|---|---|
| username required | The username (email address) of the user. |
| password required | The password of the user. |
Permissions
This API call requires no specific permissions.
Headers
The following headers can/must be passed to the API call:
X-Spaaza-MyPrice-App-Hostname (mandatory in some cases) The hostname of the app which the signup is for. This header is mandatory when authenticating an end user (shopper or programme member). When authenticating an admin user (including a webshop or POS) this header must be excluded.
Results
If the session is valid, the login call returns information about the user and the session, including: key, length of validity in hours and the authentication method used to establish the key.
An example is shown below:
[
{
"result": {
"code": 1,
"status": "ok"
},
"results": {
"result_type": "login",
"session_info": {
"session_key": "acc5cf311f4bce26feaa80de400e2f294ff6168f49da765f0a4d6a798900460f",
"session_key_validity": "336",
"session_auth_method": "password",
"session_user_id": 114521,
"session_username": "test56767@spaaza.com",
"session_expires_date": "2020-04-06 11:19:10"
},
"user_info": {
"id": 114521,
"user_id": 114521,
"first_name": "Sam",
"last_name": "Critchley",
"gender": "M",
"birthday": "2014-10-21",
"username": "test56767@spaaza.com",
"mailing_list": {
"mailing_list_sub_offered": "true",
"mailing_list_subscribed": false,
"printed_mailing_list_subscribed": false
},
"entity_code": {
"type": "custom",
"code": "3021879"
},
"opt_in_programme": {
"programme_opted_in": true,
"join_date": "2016-01-30T14:37:22+00:00"
},
"registered": true,
"loyalty_status": {
"campaign_id": 2095,
"name": "Level 1",
"description": "Level 1 in the Programme",
"loyalty_level_id": 2,
"points_to_proceed_next_level": 500,
"points_to_remain_current_level": 220,
"maintenance_points_level": 200,
"last_review_date": "2019-04-04T00:05:22+00:00",
"next_review_date": "2020-04-04T00:05:22+00:00",
"date_reached": "2019-06-06T08:06:14+00:00"
}
}
}
}
]
If the user is an admin, 2FA is enabled, which means that the output will have a session passcode key and session passcode expiry date. The user will be emailed a 6-digit session passcode. If the admin user is exempt from 2FA (login_2fa_exempt is true), the login response returns session_info and user_info directly and does not include a passcode.
The user must then use the session passcode and session passcode key to obtain a session via the session endpoint.
An example is below:
[
{
"result": {
"code": 1,
"status": "ok"
},
"results": {
"session_passcode_expiry_date": "2025-06-27T15:22:31+00:00",
"session_passcode_key": "7a1c19d5evceb17c9116fac5b0f4bd22",
"result_type": "login"
}
}
]