SMS Auth Services API Documentation

Use these web services to build an SMS-based login system for China.

API Base URL

You will be assigned a base URL by your account manager. Use it along with the endpoints below to access the Auth services.

Endpoint: POST /get-code

Use this API to send an SMS authentication code to the user’s phone.

Request:

• HTTP Method: POST
• Format: JSON

{
    "key": "<API_KEY>",
    "phone_no": "<PHONE_NO>"
}

Response (if successful)

{
    "status": "ok",
    "phone_no": "<PHONE_NO>"
}

Response (if failed)

{
    "code": "<ERROR CODE>",
    "msg": "<MESSAGE>"
}

Fields

• key: Your API key, assigned by your account manager.
• phone_no: The user’s phone number where the authentication code will be sent.
• status: Returns ok if the request is successful.
• code: An error code returned when the request fails. Refer to the error code section for details.
• msg: A short message returned when the request fails. Refer to the error code section for details.

Error Codes and Definitions

• 0070: Request format is not JSON.
• 0072: Missing arguments phone_no or key in the JSON.
• 0073: Invalid key. Contact your account manager to obtain an API key.
• 0075: Invalid phone number.
• 0077: Test phone no.

Endpoint: POST /check-code

Use this API to login or register a new user when a valid SMS authentication code is entered.

Request

• HTTP Method: POST
• Format: JSON

{
    "key": "<API_KEY>",
    "phone_no": "<PHONE_NO>",
    "user_input_code": "..."
}

Response (if successful)

{
  "status": "ok",
  "yb_uid": "<>"
}

Response (if failed)

{
    "code": "<ERROR CODE>",
    "msg": "<MESSAGE>"
}

Fields

• key: Your API key, assigned by your account manager.
• phone_no: The user’s phone number where the authentication code will be sent.
• user_input_code: The code entered by the user.
• status: Returns ok if the request is successful.
• yb_uid: Returned when the user is registered or logged in successfully. Pass this UID to your app to enable the tunnel.
• code: An error code returned when the request fails. Refer to the error code section for details.
• msg: A short message returned when the request fails. Refer to the error code section for details.

Error Codes and Definitions

• 0070: Request format is not JSON.
• 0072: Missing arguments phone_no or key in the JSON.
• 0073: Invalid key. Contact your account manager to obtain an API key.
• 0075: Invalid phone number.
• 0076: Invalid format of SMS authentication code.
• 0077: Invalid or expired code.
• 0078: System error. Failed to create tunnel configuration.
• 0079: System error. Failed to create tunnel configuration.
• 0100: Insufficient balance in your account.
• -1: Unexpected system error.

Test Phone Number and Code

You can use this phone number and SMS authentication code to bypass the authentication process for testing purposes only.

{
    "key": "<API_KEY>",
    "phone_no": "12345678910",
    "user_input_code": "4433"
}

Endpoint: POST /u/<yb_uid>/devices

Use this API to create a new device for the user.

Request

• HTTP Method: POST
• Format: JSON

{
    "key": "<API_KEY>"
}

Response (if successful)

{
  "status": "ok",
  "device_id": "<DEVICE_ID>"
}

Response (if failed)

{
    "code": "<ERROR CODE>",
    "msg": "<MESSAGE>"
}

Fields

• key: Your API key, assigned by your account manager.
• status: Returns ok if the request is successful.
• device_id: Returned when a new device is created successfully. Pass this ID to your app to enable the tunnel.
• code: An error code returned when the request fails. Refer to the error code section for details.
• msg: A short message returned when the request fails. Refer to the error code section for details.

Error Codes and Definitions

• 0070: Request format is not JSON.
• 0071: Missing arguments key in the JSON.
• 0073: Invalid key. Contact your account manager to obtain an API key.
• 0078: System error. Failed to create tunnel configuration.
• 0079: System error. Failed to create tunnel configuration.
• 0200: Invalid UID.
• 0202: User does not exist.
• -1: Unexpected system error.

Endpoint: GET /u/<yb_uid>/devices

Use this API to get a list of devices that a user owns.

Request

• HTTP Method: GET

Response (if successful)

{
  "status": "ok",
  "device_ids": [
      "<DEVICE_ID_1>",
      "<DEVICE_ID_2>",
      ...
  ]
}

Response (if failed)

{
    "code": "<ERROR_CODE>",
    "msg": "<MESSAGE>"
}

Fields

• status: Returns ok if the request is successful.
• device_ids: Returns a list of devices that the user owns. Only the 10 most recent created devices will be shown here.
• code: An error code returned when the request fails. Refer to the error code section for details.
• msg: A brief message returned when the request fails. Refer to the error code section for details.

Error Codes and Definitions

• 0200: Invalid UID.
• 0202: User does not exist.
• -1: Unexpected system error.