API Support
This appendix discusses API support for the Cisco NAC Guest Server. It describes the following:
•
Overview
•
Authentication Requirements
•
Time Format
•
API Operations
•
Status Codes
•
Error Codes
•
Valid Timezones
Overview
Cisco NAC Guest Server provides an API that allows you to perform certain operations using HTTP or HTTPS via POST or GET operations. The NAC Guest Server API is accessed via https://serveripaddress/sponsor/api/GuestAccount.php or http://serveripaddress//sponsor/api/GuestAccount.php.
To use this API, note the following:
•
Competency with a programming language (e.g. C, Java, Perl, PHP) is required and you must install the relevant software on the machine that runs these programs to call this API.
•
Cisco TAC does not support debugging of custom programs using the API. It only supports running API calls.
Authentication Requirements
Access over HTTP or HTTPS for the API is based upon the SSL settings for the web Administration interface as defined in Accessing the Guest Server Using HTTP or HTTPS.
A valid username and password is also required to authenticate as a sponsor against the following components:
•
Local database
•
Active directory server as defined in admin settings
•
LDAP server as defined in admin settings
•
RADIUS as defined in admin settings
For example, the following call uses the username "sponsor" with password "mypass":
http://1.1.1.1/sponsor/api/GuestAccount.php?username=sponsor&password=mypass&method=create
&firstName=John&surname=Carter&email=test@cisco.com&role=DEFAULT&company=Cisco&mobileNumbe
r=1234548434532&phoneCode=123&startTime=20100210T10%3A45%3A00&endTime=20100211T13%3A15%3A0
0&timezone=Europe%2FLondon&timeProfile=default
Note
All fields must be URL encoded. For example, date/time fields have been encoded so that the colon is replaced with %3A.
Time Format
All dates/times must be specified in a particular ISO 8601 format: YYYYMMDDTHH:MM:SS where:
•
YYYY is the 4-digit year
•
MM is the 2-digit month
•
DD is the 2-digit day of the month
•
T is a literal T
•
HH is the 2-digit hour (24 hour format)
•
MM is the 2-digit minute
•
SS is the 2-dogit second
Example: 20100304T08:45:30 is 4 March 2010, 08:45:30
See http://en.wikipedia.org/wiki/ISO_8601 for details.
API Operations
You can use the API by passing the details either through a POST or GET operation to the Cisco NAC Guest Server API.
The following example shows a GET operation to obtain the version of the API and Cisco NAC Guest Server.
https://1.1.1.1/sponsor/api/GuestAccount.php?username=sponsor&password=mypass&method=getVe
rsion
All data is returned as XML.
XML Response
All responses are provided in the following XML format:
<message>Success</message>
In the case of an error, the code and message elements are set with the error code and error text. Internal errors also return a <details> element that contains developer information to help address the issue.
create
The create method creates a guest user account in accordance with the sponsor's permissions.
Required In Parameters
•
method (required): create
•
username (required): Sponsor account username
•
password (required): Sponsor account password
•
firstName (based on policy): Guest user first name
•
surname (based on policy): Guest user surname
•
email (based on policy): Guest user email address
•
role (required): The role in which the guest user is created
•
company (based on policy): Guest user company name
•
phonecode (based on policy): Telephone code for the Guest user mobile telephone (e.g. +44)
•
mobilenumber (based on policy): Mobile telephone number for the Guest user
•
timezone (required): The timezone in which the guest account is created (as detailed in Valid Timezones)
•
option1 (based on policy): Optional data field 1
•
option2 (based on policy): Optional data field 2
•
option3 (based on policy): Optional data field 3
•
option4 (based on policy): Optional data field 4
•
option5 (based on policy): Optional data field 5
•
startTime (required): The time the account is due to start
•
endTime (required): The time the account should end
•
timeProfile (required): The time profile to use when creating the account
create Example Use
Step 1
The following example creates an account with the following guest details:
First Name: John
Surname: Carter
Email: johncart@cisco.com
Role: DEFAULT (as created in the user role interface)
Company: Cisco
Mobile Number (cellphone): 12345 48434532
Phone Code: 123
Start Time: 29th November 2008 (midnight)
EndTime: 30th November 2008 (midnight)
Timezone: Europe/London
Time Profile: StartEnd (as created in the time profile user interface)
Step 2
Call the API as follows:
http://x.x.x.x/sponsor/api/GuestAccount.php?username=local&password=local&method=create&fi
rstName=John&surname=Carter&email=johncart%40cisco.com&role=DEFAULT&company=Cisco&mobileNu
mber=12345+48434532&phoneCode=123&startTime=2008-11-29&endTime=2008-11-30&timezone=Europe%
2FLondon&timeProfile=StartEnd
Step 3
If succesful, a response is returned:
<message>Success</message>
<firstName>John</firstName>
<surname>Carter</surname>
<email>johncart@cisco.com</email>
<mobileNumber>12345 48434532</mobileNumber>
<phoneCode>123</phoneCode>
<username>JohnCarter10</username>
<password>!B,4N!32(F1{VJ2</password>
<timezone>Europe/London</timezone>
<startTimeT>2008-11-29T00:00:00+00:00</startTimeT>
<endTimeT>2008-11-30T00:00:00+00:00</endTimeT>
<modifiedUsername>1</modifiedUsername>
<accountType>1</accountType>
<durationUnit>Days</durationUnit>
<durationInUnits>0</durationInUnits>
<startTime>00:00</startTime>
<startTime>00:00</startTime>
<startTime>17:00</startTime>
<startTime>17:00</startTime>
<startTime>00:00</startTime>
<startTime>00:00</startTime>
edit
The edit method edits an existing user account in accordance with sponsor's permissions.
You may edit any of the fields associated with an existing account with the following exceptions:
•
start time
•
role
•
time profile
•
time zone
To edit an account, you must supply the account ID as returned by the create method.
Required In Parameters
•
method (required): edit
•
id (required): The database ID of the account to be edited
•
username (required): Sponsor account username
•
password (required): Sponsor account password
•
firstName (optional): Guest user first name
•
surname (optional): Guest user surname
•
email (optional): Guest user email address
•
group (optional): The role in which the guest user is created
•
company (optional): Guest user company name
•
phonecode (optional): Telephone code for the Guest user mobile telephone (e.g. +44)
•
cellnumber (optional): Cell telephone number for the Guest user
•
timezone (optional): The timezone in which the guest account is created (as detailed in Valid Timezones)
•
option1 (optional): Optional data field 1
•
option2 (optional): Optional data field 2
•
option3 (optional): Optional data field 3
•
option4 (optional): Optional data field 4
•
option5 (optional): Optional data field 5
•
startTime (optional): The time the account is due to start
•
endTime (optional): The time the account should end
•
timeProfile (optional): The time profiler to use when creating the account
edit Example Use
The following example changes the mobile phone (cell phone) number for the account with ID 794:
http://x.x.x.x/sponsor/api/GuestAccount.php?username=local&password=local&method=edit&id=7
94&mobileNumber=12345678
The full account detail is returned as with the getDetails method.
<message>Success</message>
<firstName>John</firstName>
<surname>Carter</surname>
<email>johncart@cisco.com</email>
<mobileNumber>12345678</mobileNumber>
<phoneCode>123</phoneCode>
<username>jcarter</username>
<password>cisco</password>
<timezone>Europe/London</timezone>
<startTimeT>2008-10-28T00:00:00+00:00</startTimeT>
<endTimeT>2008-10-29T00:00:00+00:00</endTimeT>
<startTime>2008-08-07T04:06:32+01:00</startTime>
<endTime>2008-08-07T04:06:33+01:00</endTime>
<ipAddress>4.5.6.7</ipAddress>
<startTime>2008-10-02T22:00:00+01:00</startTime>
<endTime>2008-10-03T00:30:00+01:00</endTime>
<ipAddress>4.5.6.7</ipAddress>
<accountType>1</accountType>
<durationUnit>Days</durationUnit>
<durationInUnits>0</durationInUnits>
<startTime>00:00</startTime>
<startTime>00:00</startTime>
<startTime>17:00</startTime>
<startTime>17:00</startTime>
<startTime>00:00</startTime>
<startTime>00:00</startTime>
getDetails
The getDetails API gets a user's account details in accordance with the sponsor's permissions.
Required In Parameters
•
method (required): getDetails
•
username (required): Sponsor account username
•
password (required): Sponsor account password
•
id (one required): ID of the account to be retrieved
getDetails Example Use
Step 1
To get details for an existing account, use the getDetails API call, passing in the ID of the account as returned by the create method:
http://x.x.x.x/sponsor/api/GuestAccount.php?username=local&password=local&method=getDetail
s&id=815
Step 2
If succesful the following response will be returned:
<message>Success</message>
<firstName>John</firstName>
<surname>Carter</surname>
<email>johncart@cisco.com</email>
<mobileNumber>12345 48434532</mobileNumber>
<phoneCode>123</phoneCode>
<username>jcarter</username>
<password>*****</password>
<timezone>Europe/London</timezone>
<startTimeT>2008-10-29T00:00:00+00:00</startTimeT>
<endTimeT>2008-10-30T00:00:00+00:00</endTimeT>
<startTime>2008-08-07T04:06:32+01:00</startTime>
<endTime>2008-08-07T04:06:33+01:00</endTime>
<ipAddress>4.5.6.7</ipAddress>
<startTime>2008-10-02T22:00:00+01:00</startTime>
<endTime>2008-10-03T00:30:00+01:00</endTime>
<ipAddress>4.5.6.7</ipAddress>
<accountType>1</accountType>
<durationUnit>Days</durationUnit>
<durationInUnits>0</durationInUnits>
<startTime>00:00</startTime>
<startTime>00:00</startTime>
<startTime>17:00</startTime>
<startTime>17:00</startTime>
<startTime>00:00</startTime>
<startTime>00:00</startTime>
suspend
The suspend method suspends a user account in accordance with sponsor's permissions.
Required In Parameters
•
method (required): suspend
•
username (required): Sponsor account username
•
password (required): Sponsor account password
•
id (required): The database ID of the account to be suspended
suspend Example Use
The suspend method suspends the account and returns the same XML response as getDetails.
http://x.x.x.x/sponsor/api/GuestAccount.php?username=local&password=local&method=suspend&&
&&id=815
notifyEmail
The notifyEmail method sends an email message to the guest's email account. It returns the same XML as getDetails.
Required In Parameters
•
method (required): notifyEmail
•
username (required): Sponsor account username
•
password (required): Sponsor account password
•
id (required): The database ID of the account to be emailed
•
from (required): The email address from which to send the email
•
to (required): the email address to send the email to
notifyEmail Example Use
http://x.x.x.x/sponsor/api/GuestAccount.php?username=local&password=local&method=notifyEma
il.&&&&id=815.
notifySms
The notifySms method sends an SMS message to the guest's mobile (cell) phone. It returns the same XML as getDetails.
Required In Parameters
•
method (required): notifySms
•
username (required): Sponsor account username
•
password (required): Sponsor account password
•
id (required): The database ID of the account to be emailed
notifySms Example Use
http://x.x.x.x/sponsor/api/GuestAccount.php?username=local&password=local&method=notifySms
&&&&id=815.
getVersion
The getVersion method shows the current API version.
Required In Parameters
•
method (required): getVersion
•
username (required): Sponsor account username
•
password (required): Sponsor account password
getVersion Example Use
A call return a response of the form:
<message>Success</message>
<appName>Cisco NAC Guest Server</appName>
<majorVersion>2</majorVersion>
<minorVersion>0</minorVersion>
<maintenanceVersion>2</maintenanceVersion>
search
The search API returns guest account details for reporting purposes according to the sponsor's permissions and configuration, as per the Managing Guest Accounts of the sponsor interface.
Note
The search API is only available from version 2.0.1 and later.
Required In Parameters
•
username (required): sponsor account username
•
password (required): sponsor account password
•
method (required): search
•
sponsor (optional): sponsor username
•
firstName (optional): guest user first name
•
surname (optional): guest user surname
•
company (optional): guest user company name
•
email (optional): guest user email address
•
ipAddress (optional)
•
startTime (optional): YYYY-MM-DD
•
endTime (optional): YYYY-MM-DD
•
timezone (optional): Timezone in which the account is created
•
option1 (optional):
•
option2 (optional):
•
option3 (optional):
•
option4 (optional):
•
option5 (optional):
•
statusInactive (optional):
•
statusActive (optional):
•
stautsExpired (optional):
•
statusSuspended (optional):
search Example Use
The required parameters are mandatory. The optional parameters serve to subset the data returned. If the start and end date are not specified, then accounts spanning the last 24 hours are returned.
The following example returns details of active guest accounts between 3rd March 2009 and 15th April 2009.
http://x.x.x.x/sponsor/api/GuestAccount.php?username=local&password=local&method=search&startTime=2009-03-03&endTime=2009-04-15&statusActive=1
If successful, the following response will be returned.
<message>Success</message>
<firstName>Jim</firstName>
<company>Beans Brewery</company>
<email>jim@bean.com</email>
<username> jim@bean.com </username>
<password>Es3TDdd3</password>
<mobileNumber>782394928</mobileNumber>
<timezone>America/Los_Angeles</timezone>
<startTimeT>2009-04-01T04:40:00-07:00</startTimeT>
<endTimeT>2009-04-06T06:59:00-07:00</endTimeT>
<sponsorId>196</sponsorId>
<timeProfileId>1</timeProfileId>
<timeProfile>default</timeProfile>
...further account details meeting the request criteria...
...further account details meeting the request criteria...
...further account details meeting the request criteria...
search Example Use with StartTime, EndTime, Timezone
The "timezone" parameter refers to the Timezone in which the account has been created.
The following example returns details of active guest accounts created with time zone "Europe/Moscow", where the start time and end time overlap with the specified start time (2012-07-01 21:22:00) and end time (2012-07-02 23:59:00).
The "timezone" is the mandatory parameter for the "search" API to fetch the records for the specified Start Time / End Time, in the search query.
http://x.x.x.x/sponsor/api/GuestAccount.php?username=local&password=local&method=search&startTime=2012-07-01T21:22:00+01:00&endTime=2012-07-02T23:59:00+01:00&timezone=Europe%2FMoscow
If successful, the following response is returned:
<message>Success</message>
<firstName>Jim</firstName>
<company>Beans Brewery</company>
<email>jim@bean.com</email>
<username>jim@bean.com</username>
<password>Es3TDdd3</password>
<mobileNumber>782394928</mobileNumber>
<timezone>Europe/Moscow</timezone>
<startTimeT>2012-07-01T13:44:00+04:00</startTimeT>
<endTimeT>2012-07-01T15:50:00+04:00</endTimeT>
<sponsorId>196</sponsorId>
<timeProfileId>1</timeProfileId>
<timeProfile>default</timeProfile>
If you run search API without the timezone parameter, then the sponsor's time zone is applied to the start time and end time. The following query returns records with the timezone of the user "local".
http://x.x.x.x/sponsor/api/GuestAccount.php?username=local&password=local&method=search&startTime=2012-07-01T10:52:00&endTime=2012-07-03T01:30:00
The start time and end time parameters are displayed in the time zone in which the users are created.
Status Codes
The account status is returned via XML and contains the following values:
•
Status inactive = 1
•
Status active = 2
•
Status expired = 3
•
Status suspended = 4
Error Codes
The following error codes are returned in the <code> element of the response.
Value - Description:
•
Value 0—No error
•
Value 1—Internal application error
•
Value 100—Incorrect sponsor username and/or password
•
Value101—Cannot access API via HTTPS (controlled by administrator)
•
Value102—Cannot access API via HTTP (controlled by administrator)
•
Value 1000—Some required fields are missing (listed in the message)
•
Value1001—Sending SMS messages disabled by administrator
•
Value1002—Sending Emails disabled by administrator
•
Value1003—The passed account ID does not exist
•
Value1004—Some fields are incorrect (listed in the message)
•
Value 1005—Some fields cannot be changed using the edit method
Valid Timezones
Africa/Abidjan Africa/Accra Africa/Addis_Ababa Africa/Algiers Africa/Asmara Africa/Bamako Africa/Bangui Africa/Banjul Africa/Bissau Africa/Blantyre Africa/Brazzaville Africa/Bujumbura Africa/Cairo Africa/Casablanca Africa/Ceuta Africa/Conakry Africa/Dakar Africa/Dar_es_Salaam Africa/Djibouti Africa/Douala Africa/El_Aaiun Africa/Freetown Africa/Gaborone Africa/Harare Africa/Johannesburg Africa/Kampala Africa/Khartoum Africa/Kigali Africa/Kinshasa Africa/Lagos Africa/Libreville Africa/Lome Africa/Luanda Africa/Lubumbashi Africa/Lusaka Africa/Malabo Africa/Maputo Africa/Maseru Africa/Mbabane Africa/Mogadishu Africa/Monrovia Africa/Nairobi Africa/Ndjamena Africa/Niamey Africa/Nouakchott Africa/Ouagadougou Africa/Porto-Novo Africa/Sao_Tome Africa/Tripoli Africa/Tunis Africa/Windhoek America/Adak America/Anchorage America/Anguilla America/Antigua America/Araguaina America/Argentina/Buenos_Aires America/Argentina/Catamarca America/Argentina/Cordoba America/Argentina/Jujuy America/Argentina/La_Rioja America/Argentina/Mendoza America/Argentina/Rio_Gallegos America/Argentina/San_Juan America/Argentina/Tucuman America/Argentina/Ushuaia America/Aruba America/Asuncion America/Atikokan America/Bahia America/Barbados America/Belem America/Belize America/Blanc-Sablon America/Boa_Vista America/Bogota America/Boise America/Cambridge_Bay America/Campo_Grande America/Cancun America/Caracas America/Cayenne America/Cayman America/Chicago America/Chihuahua America/Costa_Rica America/Cuiaba America/Curacao America/Danmarkshavn America/Dawson America/Dawson_Creek America/Denver America/Detroit America/Dominica America/Edmonton America/Eirunepe America/El_Salvador America/Fortaleza America/Glace_Bay America/Godthab America/Goose_Bay America/Grand_Turk America/Grenada America/Guadeloupe America/Guatemala America/Guayaquil America/Guyana America/Halifax America/Havana America/Hermosillo America/Indiana/Indianapolis America/Indiana/Knox America/Indiana/Marengo America/Indiana/Petersburg America/Indiana/Tell_City America/Indiana/Vevay America/Indiana/Vincennes America/Indiana/Winamac America/Inuvik America/Iqaluit America/Jamaica America/Juneau America/Kentucky/Louisville America/Kentucky/Monticello America/La_Paz America/Lima America/Los_Angeles America/Maceio America/Managua America/Manaus America/Martinique America/Mazatlan America/Menominee America/Merida America/Mexico_City America/Miquelon America/Moncton America/Monterrey America/Montevideo America/Montreal America/Montserrat America/Nassau America/New_York America/Nipigon America/Nome America/Noronha America/North_Dakota/Center America/North_Dakota/New_Salem America/Panama America/Pangnirtung America/Paramaribo America/Phoenix America/Port-au-Prince America/Port_of_Spain America/Porto_Velho America/Puerto_Rico America/Rainy_River America/Rankin_Inlet America/Recife America/Regina America/Resolute America/Rio_Branco America/Santiago America/Santo_Domingo America/Sao_Paulo America/Scoresbysund America/Shiprock America/St_Johns America/St_Kitts America/St_Lucia America/St_Thomas America/St_Vincent America/Swift_Current America/Tegucigalpa America/Thule America/Thunder_Bay America/Tijuana America/Toronto America/Tortola America/Vancouver America/Whitehorse America/Winnipeg America/Yakutat America/Yellowknife Antarctica/Casey Antarctica/Davis Antarctica/DumontDUrville Antarctica/Mawson Antarctica/McMurdo Antarctica/Palmer Antarctica/Rothera Antarctica/South_Pole Antarctica/Syowa Antarctica/Vostok Arctic/Longyearbyen Asia/Aden Asia/Almaty Asia/Amman Asia/Anadyr Asia/Aqtau Asia/Aqtobe Asia/Ashgabat Asia/Baghdad Asia/Bahrain Asia/Baku Asia/Bangkok Asia/Beirut Asia/Bishkek Asia/Brunei Asia/Calcutta Asia/Choibalsan Asia/Chongqing Asia/Colombo Asia/Damascus Asia/Dhaka Asia/Dili Asia/Dubai Asia/Dushanbe Asia/Gaza Asia/Harbin Asia/Hong_Kong Asia/Hovd Asia/Irkutsk Asia/Jakarta Asia/Jayapura Asia/Jerusalem Asia/Kabul Asia/Kamchatka Asia/Karachi Asia/Kashgar Asia/Katmandu Asia/Krasnoyarsk Asia/Kuala_Lumpur Asia/Kuching Asia/Kuwait Asia/Macau Asia/Magadan Asia/Makassar Asia/Manila Asia/Muscat Asia/Nicosia Asia/Novosibirsk Asia/Omsk Asia/Oral Asia/Phnom_Penh Asia/Pontianak Asia/Pyongyang Asia/Qatar Asia/Qyzylorda Asia/Rangoon Asia/Riyadh Asia/Saigon Asia/Sakhalin Asia/Samarkand Asia/Seoul Asia/Shanghai Asia/Singapore Asia/Taipei Asia/Tashkent Asia/Tbilisi Asia/Tehran Asia/Thimphu Asia/Tokyo Asia/Ulaanbaatar Asia/Urumqi Asia/Vientiane Asia/Vladivostok Asia/Yakutsk Asia/Yekaterinburg Asia/Yerevan Atlantic/Azores Atlantic/Bermuda Atlantic/Canary Atlantic/Cape_Verde Atlantic/Faroe Atlantic/Jan_Mayen Atlantic/Madeira Atlantic/Reykjavik Atlantic/South_Georgia Atlantic/Stanley Atlantic/St_Helena Australia/Adelaide Australia/Brisbane Australia/Broken_Hill Australia/Currie Australia/Darwin Australia/Eucla Australia/Hobart Australia/Lindeman Australia/Lord_Howe Australia/Melbourne Australia/Perth Australia/Sydney Europe/Amsterdam Europe/Andorra Europe/Athens Europe/Belgrade Europe/Berlin Europe/Bratislava Europe/Brussels Europe/Bucharest Europe/Budapest Europe/Chisinau Europe/Copenhagen Europe/Dublin Europe/Gibraltar Europe/Guernsey Europe/Helsinki Europe/Isle_of_Man Europe/Istanbul Europe/Jersey Europe/Kaliningrad Europe/Kiev Europe/Lisbon Europe/Ljubljana Europe/London Europe/Luxembourg Europe/Madrid Europe/Malta Europe/Mariehamn Europe/Minsk Europe/Monaco Europe/Moscow Europe/Oslo Europe/Paris Europe/Podgorica Europe/Prague Europe/Riga Europe/Rome Europe/Samara Europe/San_Marino Europe/Sarajevo Europe/Simferopol Europe/Skopje Europe/Sofia Europe/Stockholm Europe/Tallinn Europe/Tirane Europe/Uzhgorod Europe/Vaduz Europe/Vatican Europe/Vienna Europe/Vilnius Europe/Volgograd Europe/Warsaw Europe/Zagreb Europe/Zaporozhye Europe/Zurich Indian/Antananarivo Indian/Chagos Indian/Christmas Indian/Cocos Indian/Comoro Indian/Kerguelen Indian/Mahe Indian/Maldives Indian/Mauritius Indian/Mayotte Indian/Reunion Pacific/Apia Pacific/Auckland Pacific/Chatham Pacific/Easter Pacific/Efate Pacific/Enderbury Pacific/Fakaofo Pacific/Fiji Pacific/Funafuti Pacific/Galapagos Pacific/Gambier Pacific/Guadalcanal Pacific/Guam Pacific/Honolulu Pacific/Johnston Pacific/Kiritimati Pacific/Kosrae Pacific/Kwajalein Pacific/Majuro Pacific/Marquesas Pacific/Midway Pacific/Nauru Pacific/Niue Pacific/Norfolk Pacific/Noumea Pacific/Pago_Pago Pacific/Palau Pacific/Pitcairn Pacific/Ponape Pacific/Port_Moresby Pacific/Rarotonga Pacific/Saipan Pacific/Tahiti Pacific/Tarawa Pacific/Tongatapu Pacific/Truk Pacific/Wake Pacific/Wallis