Get API token

Yeastar S-Series VoIP PBX API uses username and password for authentication. PBX API only handles the requests with a valid token.

Note:

If login fails for five times, IP address of the application server will be locked for 10 minutes. You can log in PBX web interface and delete blocked API IP.

Request URL

{base_url}/{api_path}/login

Request parameters

Parameter Required Type Description
username Yes String Username in API Settings on PBX.
password Yes String Encrypt the password in API Settings on PBX using MD5 (Message-Digest Algorithm) . Enter the encrypted 32-digit lowercase string.
version No String Format version of event reports.
Note:
  • All URLs referenced in the documentation use API version v2.0.0.
  • If version is not specified, PBX will send events in version 1.0.0. We recommend that you specify the parameter to get events in correct format.
port No String

The application server would monitor the port and receive events sent from PBX through this port.

Note: If you select HTTP as report method, the parameter is required.

Default value: 8260.
url No String URL of the application server. This URL is used to specify the sending path of events to the application server.
Note:
  • The parameter is only applicable when the report method is HTTP.
  • If the parameter is not specified, the event will be sent to the IP address of the application server.
urltag No String Specify the URL type.
Note:
  • The parameter is only applicable when the report method is HTTP.
  • Using an absolute URL will ensure the API reports to be sent successfully in a complicated network environment.

Valid values:

  • 0: The URL is a relative URL.

    For example, the IP address of the application server is 110.22.2.3,port is 8260, url is "report"; PBX will send the API reports to 110.22.2.3:8260/report.

  • 1: The URL is an absolute URL.

    For example, the IP address of the application server is 110.22.2.3,url is "110.22.2.3:8260/report"; PBX will send the API reports to "110.22.2.3:8260/report".

Default values: 0.

Response parameters

Parameter Type Description
status String Request result.
  • Success.
  • Failed.
token String Credential of calling API interfaces. All requests to call API interfaces must carry a token.
transport String The transport of API events.
  • HTTP: PBX sends HTTP events by short-live TCP flows.
  • TCP: PBX sends TCP events by keep-alive TCP flows.

For events details, refer to API Events.

Examples

Request example

POST /api/v2.0.0/login HTTP/1.1
Content-Type:application/json; charset=utf-8
Host: 192.168.5.150

{
    "username": "api",
    "password": "2d7257a528679d01a19c70e3fa773870",
    "port": "8260",
    "version": "2.0.0"
}

Response example

login success.

HTTP/1.1 200 OK
Connection: close
Content-Type: application/json
Access-control-allow-origin: *
Access-control-allow-methods: GET, POST, OPTIONS, PUT, DELETE

{
    "status": "Success",
    "token": "48a7d7481a5355aa4fb5dc285edeb40e",
    "transport": "TCP"
}
Login failure.
HTTP/1.1 200 OK
Access-control-allow-origin: *
Access-control-allow-methods: GET, POST, OPTIONS, PUT, DELETE
{
      "status": "Failed", 
      "errno": "30003"
}