Authentication
Handle user login and registration

The login process (in brief): ↑

  • User sends mobile number to /auth/send_pin

  • If the user exists, the server sends a 4-digit pin (OTP code) via SMS to the mobile number

  • Server responds with otp_auth_key

  • User calls /auth/verify with OTP code AND otp_auth_key

  • Server successfully authenticates and returns jwt_token

  • jwt_token is sent with all API requests requiring authorization

Diagrams ↑

A fuller explanation of the user login / registration process is detailed in the following flowchart diagrams.

JWT Token ↑

When sending the JWT token to authenticate each request, place it in the request header using the “Authorization Bearer” scheme. Example: Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE0MTc1NzkwMTQsImlzcyI6Ikdvb2RDaXR5VGVzdCIsImV4cCI6MTQxNzU4MDgxNH0.x-N_aUb3S5wcNy5i2w2WUZjEA2ud_81u8yQV0JfsT6A

Supported Formats

json
>>>

POST /api/v1/auth/send_pin
Send SMS code to the registered mobile

Send an OTP code via SMS if the given mobile number has an account in the system. Each time a new OTP code is generated, the otp_auth_key is cycled. The client is responsible for sending back the newest otp_auth_key with the OTP code. If the user account doesn't exist, a random otp_auth_key is returned.

Response status codes ↑

  • 200 - returned regardless of whether mobile number exists or not

  • 422 - returned if the mobile number is invalid

Supported Formats

json

Errors

Code Description
401 Unauthorized
422 Invalid mobile number - if mobile prefix doesn't start with +852
500 Internal Server Error

Examples

// This is an example of send pin with valid host and valid mobile number
POST /api/v1/auth/send_pin
{
  "mobile": "+85261677528"
}
200
{
  "otp_auth_key": "/JqONEgEjrZefDV3ZIQsNA=="
}
// This is an example of send pin unregistered mobile number
POST /api/v1/auth/send_pin
{
  "mobile": "+85251641822"
}
200
{
  "otp_auth_key": "/JqONEgEjrZefDV3ZIQsNA=="
}
// This is an example of send pin with invalid host
POST /api/v1/auth/send_pin
{
  "mobile": "+85260274677"
}
403
{
  "errors": "Invalid host"
}
// This is an example of send pin with empty mobile number
POST /api/v1/auth/send_pin
{
  "mobile": ""
}
422
{
  "errors": "Mobile can't be blank"
}
// This is an example of send pin with invalid mobile number
POST /api/v1/auth/send_pin
{
  "mobile": "+9101234567"
}
422
{
  "errors": "Mobile must begin with +852"
}

Params

Param name Description
mobile
optional

Mobile number with prefixed country code e.g. +85262345678

Validations:

  • Must be a String
>>>

POST /api/v1/auth/signup_and_send_pin
Register a new user

Supported Formats

json
>>>

POST /api/v1/auth/signup
Register a new user

Create a new user and send an OTP token to the user's mobile. If the mobile number already exists, do not create a new user. Send an OTP code to the existing user's mobile and disregard any other signup params.

If successful: ↑

  • an OTP code will be sent via SMS to the user's mobile

  • an otp_auth_key will be returned to the client

Hong Kong mobile numbers ↑

  • must begin with +8525, +8526, or +8529

  • must contain a further 7 digits.

Valid examples: ↑

  • +85251234567

  • +85261234567

  • +85291234567

Invalid examples: ↑

  • +11112345678 - must begin with +8525, +8526, or +8529

  • +85212345678 - must begin with +8525, +8526, or +8529

  • +8525234567 - too short

  • +852523456789 - too long

To understand the registration process in detail please refer to the attached Registration flowcharts

Supported Formats

json

Errors

Code Description
422 Validation Error
500 Internal Server Error

Examples

POST /api/v1/auth/signup
{
  "user_auth": {
    "mobile": "+85251224538",
    "first_name": "Jake",
    "last_name": "Deamon",
    "address_attributes": {
      "district_id": "1",
      "address_type": "Profile"
    }
  }
}
200
{
  "otp_auth_key": "/JqONEgEjrZefDV3ZIQsNA=="
}

Params

Param name Description
user_auth
required

Validations:

  • Must be a Hash
user_auth[mobile]
optional

Mobile number e.g. +85212345678

Validations:

  • Must be a String
user_auth[first_name]
optional

Given name (first name)

Validations:

  • Must be a String
user_auth[last_name]
optional

Family name (last name)

Validations:

  • Must be a String
user_auth[address_attributes]
required

Validations:

  • Must be a Hash
user_auth[address_attributes][district_id]
optional

Hong Kong district

Validations:

  • Must be a String
user_auth[address_attributes][address_type]
optional

Type of address e.g. 'Profile' or 'Collection'

Validations:

  • Must be a String
>>>

POST /api/v1/auth/verify
Verify OTP code

Verify the OTP code (sent via SMS)

  • If verified, generate and send back an authenticated jwt_token and user object

  • If verification fails, return 422 (Unprocessable Entity)

If successful ↑

  • a jwt_token will be returned. This should be included in all subsequent requests as part of the AUTHORIZATION header to authenticate the API calls.

  • the user object is returned.

To understand the registration process in detail refer attached Login flowchart

Supported Formats

json

Errors

Code Description
401 Unauthorized
403 Forbidden
422 Validation Error
500 Internal Server Error

Examples

POST /api/v1/auth/verify
{
  "otp_auth_key": "/JqONEgEjrZefDV3ZIQsNA==",
  "pin": "1234"
}
200
{
  "jwt_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE0MTc1NzkwMTQsImlzcyI6Ikdvb2RDaXR5VGVzdCIsImV4cCI6MTQxNzU4MDgxNH0.x-N_aUb3S5wcNy5i2w2WUZjEA2ud_81u8yQV0JfsT6A",
  "user": {
    "addresses": [
      {
        "id": 1857,
        "street": "Schmeler Parks",
        "flat": "Suite 609",
        "building": "58752",
        "district_id": 2038,
        "addressable_id": 1831,
        "addressable_type": "User"
      }
    ],
    "permissions": [],
    "user_profile": {
      "id": 1831,
      "first_name": "Reynold",
      "last_name": "Lakin",
      "mobile": "98353103",
      "address_id": 1857,
      "permission_id": null
    }
  }
}

Params

Param name Description
pin
optional

OTP code received via SMS

Validations:

  • Must be a String
otp_auth_key
optional

The authentication key received during 'send_pin' or 'signup' steps

Validations:

  • Must be a String
>>>

GET /api/v1/auth/current_user_profile
Retrieve current authenticated user profile details

Supported Formats

json

Errors

Code Description
401 Unauthorized
500 Internal Server Error

Examples

GET /api/v1/auth/current_user_profile
200
{
  "addresses": [
    {
      "id": 1861,
      "street": "Sydnie Trail",
      "flat": "Suite 258",
      "building": "8903",
      "district_id": 2042,
      "addressable_id": 1835,
      "addressable_type": "User"
    }
  ],
  "permissions": [],
  "user_profile": {
    "id": 1835,
    "first_name": "Brendon",
    "last_name": "Kerluke",
    "mobile": "60521718",
    "address_id": 1861,
    "permission_id": null
  }
}
>>>

POST /api/v1/auth/register_device
Register a mobile device to receive notifications

Supported Formats

json

Params

Param name Description
handle
optional

The registration id for the push messaging service for the platform i.e. fcm/gcm registration id for android

Validations:

  • Must be a String
platform
optional

The azure notification platform name, this should be `fcm/gcm` for android

Validations:

  • Must be a String
>>>

GET /api/v1/auth/current_user_rooms
Retrieve the list of socketio rooms the user can listen to

Supported Formats

json

Errors

Code Description
500 Internal Server Error