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.
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 is introduced, meaning a login request now returns a session passcode key and the user will be emailed a session passcode. |
| >= 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.
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"
}
}
]