Wiwiz Auth API Manual and Specification
|
[Modification Logs] Ver 1.1 : Added parameter ‘userstring’ (the Track Data). (Dec 28, 2012) Ver 1.2 : Added parameter ‘url’, to transmit initial access URL. (Mar 5, 2013) Ver 1.3 : Added the interfaces of shutting down authenticated connection. (Mar 5, 2013) Ver 1.4 : Traffic Limit Parameters are added. (Aug 1, 2014) Ver 1.5 : Added the interface of changing the time of shutting down authenticated connection. (Oct 16, 2015) Ver 1.6 : URL parameter ‘tokencode’ and ‘mac’ is added when ‘postauth’ is specified. (Oct 21, 2015) Ver 1.7 : Added the interface of changing ‘userstring’. (Aug 30, 2016) |
Description
Wiwiz Auth API is an Application Programming Interface based on Web technology, which is provided by Wiwiz HotSpot Builder. It can be integrated along with a third-party system (user’s system) to verify and authenticate clients by using web authentication.
It is very easy to integrate Wiwiz Auth API with a user’s system. All you need to do is to write a Web program under the specification of Wiwiz Auth API with any Web server-side programming language, such as ASP, C#/VB.Net, JSP/Servlet, PHP, etc.
Once you have done the integration, when a client attempts to access an arbitrary http URL with a web browser in your network, the Authentication Page – the Web program you wrote, of your network or hotspot will be displayed. His/her local account or login attempt may be verified as you need in your Web program, and he/she can access the Internet after authenticated if you allow it.
Conditions and Requirements
1.A Wiwiz Professional Account is required.
2.Get your User Key of your Wiwiz account. (*Remark 3)
3.Create a Hotspot with Wiwiz Web Panel. Set “Authentication Method” at “Authentication Settings” to “Auth with 3rd-party system (calling Wiwiz Auth API)”. Set “Auth URL” to the URL of the Web program you wrote for the user’s system. (*Remark 1)
4.Setup Wiwiz HotSpot Builder Utility in your local gateway device (Refer to the documentations of Wiwiz HotSpot Builder Utility).
API Calling Sequence Chart
API Calling Sequence
API Calling Description
(1) When a client attempts to access an arbitrary http URL with a web browser, the mechanism of web authentication will be launched. The client’s request will be redirect to “Auth URL” (*Remark 1) by Wiwiz service. Meanwhile, 3 HTTP GET incoming parameters – ‘tokencode’, ‘srvurl’ and ‘url’, will be passed to “Auth URL”. The descriptions of these parameters is listed as below:
| Parameter Name | Description |
| tokencode | A token Wiwiz service issues to the user’s system. |
| srvurl | The URL used for requesting to Wiwiz service. |
| url | The user’s initial http URL. |
(2) Do the business as you need in the user’s system, such as account verification or login validation … Refer to “Step 1” in the chart above.
(3) Once user’s business is done (e.g. login validated), call Wiwiz Auth API from the server side in the user’s system to do the pre-auth. Refer to “Step 2” in the chart above.
- The way to do the calling is to make an HTTP request to Wiwiz service from server side (not from client/browser side) (*Remark 2). The requested address should be the value of the incoming parameter “srvurl”.
- Some parameters (by HTTP GET or HTTP POST) should be set along with the request, including:
| Parameter Name | Required /Optional |
Description |
| wiwiz_auth_api | Required | Fixed Value “1” |
| ver | Required | Fixed Value “1.0” |
| tokencode | Required | Identical to the incoming parameter “tokencode”. Refer to (1) |
| userkey | Required | Your own User Key (*Remark 3) |
| action | Required | The auth flag. Set “1” to authenticate the client. Set “0” to block the client. |
| endtime | Optional | Set this parameter to specify the time to close the user’s Internet connection Format: yyyy-mm-dd hh:MM:ss e.g. 2012-05-31 21:39:00 Note: the value must be url-encoded. |
| postauth | Optional | Set this parameter to redirect to a specified URL after authenticated. E.g. http://www.wiwiz.com Note: the value should be url-encoded. |
| incoming_max | Optional | Incoming Traffic Limit. MBytes. Wiwiz monitors traffic usages, but there might be a little inaccuracy on the actual traffic due to a short delay on shutting down authenticated connections. |
| outgoing_max | Optional | Outgoing Traffic Limit. MBytes. Wiwiz monitors traffic usages, but there might be a little inaccuracy on the actual traffic due to a short delay on shutting down authenticated connections. |
- Wiwiz service returns an Http Response named “verifycode” as the verification result after it receives the request.
If there is any error, verifycode will look like “ERRX” (X stands for a 0~3 figure). (*Remark 4)
Otherwise, verifycode will be a series of hex digits.
(4) Then, complete the Authentication by calling Wiwiz Auth API again. Refer to “Step 3” in the chart above.
- The way to do the calling is to make an HTTP request to Wiwiz service from client/browser side (*Remark 5). The requested address should be the value of the incoming parameter “srvurl”.
- The following parameters (by HTTP GET or HTTP POST) should be set along with the request, including:
| Parameter Name | Required /Optional |
Description |
| wiwiz_auth_api_login | Required | Fixed Value “1” |
| tokencode | Required | Identical to the incoming parameter “tokencode”. Refer to (1) |
| verifycode | Required | the verification result from Wiwiz service. Refer to (3) |
| userstring | Optional | the Track Data, you can make it anything you need |
- Finally, the authentication is completed. The client will be redirected to the Post-authentication Page or the URL specified by parameter ‘postauth’. If ‘postauth’ is specified, the redirected URL will contain parameter ‘tokencode’ and ‘mac’ (client’s MAC address). If there is any error, the error page will be displayed along with the error code (*Remark 6).
To shut down an authenticated connection
To do so, you need to make the following HTTP request to Wiwiz service from server side :
Format: [srvurl]?disconn=2&t=[tokencode]&userkey=[userkey]
Sample: http://cp.wiwiz.com/as/s/login2/?disconn=2&t=A1398E284DC&userkey=246DD22C084BB40E
The response could be in the following patterns:
| Response | Description |
| 0 | Operation Succeeded. Connection will be shut down in dozens of seconds. |
| ERR21 | The connection does not exist or already shut down. |
| ERR22 | The HotSpot does not exist. |
| ERR23 | Invalid User Key or permission denied. |
To shut down an authenticated connection by user’s self
You may want the user to be able to shut down authenticated connection at the web server side.
All you need to do is let the user access the following web address in his own web browser:
Format: [srvurl]?disconn=1&t=[tokencode]
Sample: http://cp.wiwiz.com/as/s/login2/?disconn=1&t=A1398E284DC
The response could be in the following patterns:
| Response | Description |
| wiwiz_user_disconnect(0) | The connection will shutdown immediately. |
| wiwiz_user_disconnect(1) | The connection cannot shut down immediately, but will in 1~2 minutes. |
| wiwiz_user_disconnect(2) | The connection does not exist or already shut down. |
To change the time of shutting down an authenticated connection
You may need to change the time of shutting down an authenticated connection after being authenticated. To do so, you need to make the following HTTP request to Wiwiz service from server side :
Format: [srvurl]?set_endtime=[time]&t=[tokencode]&userkey=[userkey]
Sample: http://cp.wiwiz.com/as/s/login2/?set_endtime=2015-12-19+19:00:00&t=A1398E284DC&userkey=246DD22C084BB40E
The response could be in the following patterns:
| Response | Description |
| 0 | Operation Succeeded. Connection will be shut down in dozens of seconds. |
| ERR21 | The connection does not exist or already shut down. |
| ERR22 | The HotSpot does not exist. |
| ERR23 | Invalid User Key or permission denied. |
To change ‘userstring’ after being authenticated
You may need to change the content of ‘userstring’ after being authenticated. To do so, you need to make the following HTTP request to Wiwiz service from server side :
Format: [srvurl]?set_userstring=[userstring]&t=[tokencode]&userkey=[userkey]
Sample: http://cp.wiwiz.com/as/s/login2/?set_userstring=ABCDEFG&t=A1398E284DC&userkey=246DD22C084BB40E
Note: The value of ‘set_userstring’ needs urlencode. And HTTP POST method is recommended if you are trying to make a long HTTP request.
The response could be in the following patterns:
| Response | Description |
| 0 | Operation Succeeded. |
| ERR21 | The connection does not exist or already shut down. |
| ERR22 | The HotSpot does not exist. |
| ERR23 | Invalid User Key or permission denied. |
Remarks
Remark 1: “Auth URL” can be set in “Hotspot Settings” page of Wiwiz Web Panel. It is the web address of the Web program written for the user’s system under the specification of Wiwiz Auth API.
Remark 2: <IMPORTANT> For security reasons, the HTTP request for doing the pre-auth must be done from the server side, e.g. in the program of ASP, C#/VB.Net, JSP/Servlet, PHP…, but DO NOT do this from client/browser side with HTML or JavaScript.
Remark 3: You can get your User Key from “Menu” -> “Upgrade Options” -> “User Key” in Wiwiz Web Panel.
Remark 4: Error codes and descriptions.
| Error Code | Description |
| ERR0 | Authentication request is expired, or invalid request. |
| ERR1 | Invalid User Key |
| ERR2 | Invalid value of parameter “action” (neither “1” nor “0”) |
| ERR3 | Invalid value of parameter “endtime” |
Remark 5: The simplest way to make the request for completing the authentication is to let the browser access/redirect specified URL. You can do this either by issuing a Redirect statement from the server side, or by using HTML/JavaScript from the client/browser side.
Remark 6: Error codes and descriptions.
| Error Code | Description |
| ERR0 | Authentication request is expired, or invalid request. |
| ERR1 | Invalid User Key |
| ERR2 | Invalid value of parameter “action” (neither “1” nor “0”) |
| ERR3 | Invalid value of parameter “endtime” |
| ERR4 | Invalid value of parameter “verifycode” |
| ERR5 | Parameter “action” is set to 0, which means the client is blocked. |
SEE ALSO
Wiwiz Auth API Integration Sample (Java/JSP)