API Resource URL
https://<device_ip_address>/api/<function endpoint>
e.g. https://192.168.1.1/api/status.wan.connection
Authentication – with Admin User account
As in Web Admin Access, Admin User account can access the API with the user name and password. After successfully login, the session will be authorized for subsequent access to the allowed APIs.
The session id is returned from cookie named “bauth” under Secure HTTP access.
Authentication – with Client ID
API can be accessed with Client ID / secret, generated in advanced from the authenticated user, without disclosing the user name and password information.
Successfully authorization with Client ID / secret with be granted with access token, which can be used along subsequent access to the allowed APIs
Permission
- Read-Only Permission – It can only read the status and the config.
- Read-Write Permission – It can read the status and the config. It can also change the config.
- Admin Permission – It can manage the client and the token. It also have the “Read-Write Permission”
Admin Permission can only be granted by an admin user account login
Create Client
Admin Permission is needed to create the client
POST the name and scope by using the API call /api/auth.client endpoint Example:
POST /api/auth.client HTTP/1.1 Host: 192.168.1.1 Content-Type: application/json
{
"name": "Client 1",
"scope": "api.read-only"
}
Successful request will return client ID and client secret.
Generate token
POST the client ID, client secret and scope(optional) by using the API call /api/auth.token.grant Example:
POST /api/auth.token.grant HTTP/1.1
Host: 192.168.1.1
Content-Type: application/json
{
"clientId": "9270c250111cabab02058007bb72217e", "clientSecret": "cf5fe1c51252a058ebd6bd7d5f493cf5"
}
Matched client ID and secret will return access token.
How to use the access token
Add the access token as a GET parameter
Example:
GET /api/status.wan.connection?accessToken=43c65216eb16d779092fc40b184a1794 HTTP/1.1 Host: 192.168.1.1
Valid access token will get resource.
HTTP Method
- GET to retrieves simple data
- POST to manipulate configuration or execute various actions, along with supplied arguments in JSON format
GET Request Parameter
Parameters are passed in the query string (after the ? in the URL) Example:
GET /api/status.wan.connection?id=1&lite=yes HTTP/1.1 Host: 192.168.1.1
POST Request Parameter
Parameters in POST requests must be in JSON-encoded format
Example:
POST /api/login HTTP/1.1 Host: 192.168.1.1
Content-Type: application/json
{
"username": "admin", "password": "admin"
}
Response
API response are in JSON-encoded format. The JSON response is an JSON object, with “stat” to indicate if the request is done successfully (ok) or not (fail).
Typically, a successfully response will have an “response” describe the retrieved information or result of the request.
In failed responses, “code” is provided for the error code, and message about the failure, if any, will be described in “message”
| Type | Notation | Description | |
| stat | String | {ok fail} | ok – API call success fail – API call not success |
| response | Any | – | Any additional information of the success call will be here |
| code | Number | <int> | Error code of the API call, only appear if the API call not success |
| message | String | <String> | Error message of the API call, only appear if the API call not success |
| notice | Object | <Object> | Extra information about this API request (but not part of the normal response). For example, the notice to inform when the API is undocumented (for experimental / beta), or when it is in deprecate state or already replace with another API endpoint. |
For success API call
{
"stat": "ok"
}
Or
{
"stat": "ok",
"response": <Any JSON support type>
}
For success API call (beta)
{
"stat": "ok", "notice": {
"status": "beta"
},
"response": <Any JSON support type>
}
For failed API call
{
"stat": "fail",
"code": <int>,
"message": <string>
}