Contents

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.

Ready to try 21YunBox?

Get Started