Hosted User Provisioning

Each API consists of a URL and an optional input Payload XML. You may call the URL through any scripting language.

As a first step in using the API, the User ID that is setup (per the Prerequisites section below) must be used to invoke the login API. The login API returns a cookie which must be saved by the script and passed into the subsequent API calls.

Prerequisites

  • A User ID with access to the Open Mobile Portal and a Hosted End User Admin or Delegated Hosted End User Admin role assigned to it. You can confirm that the User ID has one of these roles by logging into the Open Mobile Portal, navigating to Account > Hosted Users, and creating, suspending, or updating a user.
  • The person writing the script and using this API must be well-versed in scripting and familiar with REST and HTTPS. iPass does not support any scripts written by your organization and provides APIs “as-is.” By using the API, you agree to the Terms of Use (pending).

cURL Sample Script

The cURL based shell script below provides an example of how to use the login API and the returned cookie in a subsequent call. In this example, the suspend API is invoked.

#!/bin/bash 
# The BASEURL in this script points to the portal 
BASEURL=https://openmobile.ipass.com 
 
echo Enter the company ID for which you need to invoke the specific API. 
read COMPANY 
 
echo Enter the username. 
read USER 
 
echo Enter password for user $USER. 
read -s PASSWORD 
 
# Login to the portal as a user who has access to the specific API. 
curl -k -c tmpCookies.txt "$BASEURL/moservices/rest/api/login?User-Agent=apiuser 
&username=$USER&password=$PASSWORD" 
# Pass back the cookie returned by the login while invoking the specific API

curl -k --request POST -b tmpCookies.txt -o output.xml "$BASEURL/moservices/rest/api/ipass/$COMPANY/mo/endUser?User-Agent=apiuser&action=suspend&id=endUserId

rm tmpCookies.txt

API Field Descriptions

Field Description Notes
fnameFirst name of the userMandatory
lnameLast name of the user.Mandatory
emailEmail address of the user.Mandatory. Must be a valid email address as this will be used for several confirmations about the authenticity of the user.
usernameThe username that will be registered in the Authentication service. Mandatory. The username must contain the domain the company is set up with.
passwordThe password for this user.Mandatory if company's password is user-specified, but optional if company's password policy is system-generated.
enablePortalLoginIf specified, must be set to true or false. Optional. This tag can be omitted. If omitted, the value will default to false. Setting this field to true allows the user to log in to the Open Mobile Portal (openmobile.ipass.com ) and provides access to the dashboard. Access to other functions on the portal may be given later by assigning roles to the user from the Open Mobile Portal.
departmentCodeCan be used to group users into cost-centers or departments.Optional.
startDateThe datewhen a user registers and enters our system (or is entered).Read only.
homeCountryCountry where the user is based. Optional. Helps benchmark how much a user saves by using Open Mobile versus other roaming services.
notificationsAllows the user to subscribe to emails for activation, suspension, and other notifications.Optional. If this section is omitted, subscribe defaults to true for both Activation and Suspension emails. Allows the user to subscribe to notifications by setting the attribute “subscribe” to true or false, and the parameter “type” to activate, suspend, or any other type of notification.

Create or Update User

1. Create or Update URL

NOTE: You can create or update a user, depending on whether their username already exists in the database. If you are updating a user, the only mandatory field in the XML payload is the username.

Use the following sample replacing <companyid> with the Company ID that will be using this API:

openmobile.ipass.com/moservices/rest/api/ipass/<companyid>/mo/endUser?action=createOrUpdate 

2. Input XML

Please adhere to the way lowercase and uppercase text is displayed below as some values are case-sensitive.

The sample below includes the important fields.

<endUser> 
 <fname>Favorite4</fname> 
 <lname>Subscriber</lname> 
 <email>subscriber4@subscriptioncompany.com</email> 
 <homeCountry>Country</homeCountry> 
 <username>subscriber4@subcomp.com</username> 
 <password>password</password> 
 <enablePortalLogin>false</enablePortalLogin> 
 <departmentCode>Accounting</departmentCode> 
 <!-- optional notifications section --> 
 <notifications> 
 <notification subscribe="true"><type>Activate</type></notification> 
 <notification subscribe="true"><type>Suspend</type></notification> 
 </notifications> 
</endUser>

3. Response

The system returns an XML in response.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 
<endUser> 
 <authType>HostedAuth</authType> 
 <company>companyid</company> 
 <createdBy>0</createdBy> 
 <createdTime>2013-12-13T23:01:57.751Z</createdTime> 
 <email>subscriber4@subscriptioncompany.com</email> 
 <fname>Favorite4</fname> 
 <isActive>0</isActive> 
 <lname>Subscriber</lname> 
 <modifiedBy>0</modifiedBy> 
 <modifiedTime>2013-12-13T23:01:57.751Z</modifiedTime> 
 <username>subscriber4@subcomp.com</username> 
 <departmentCode>Accounting</departmentCode> 
 <enablePortalLogin>false</enablePortalLogin> 
 <endUserId>129170</endUserId> 
 <endUserStatus>Active</endUserStatus> 
 <homeCountry>Country</homeCountry> 
 <startDate>MM/DD/YYYY</startDate> 
 <notifications> 
 <notification subscribe="true"><type>Activate</type></notification> 
 <notification subscribe="true"><type>Suspend</type></notification> 
 </notifications> 
</endUser> 
 

Suspend User

1. Suspend URL

Use the following URL, replacing the <companyid> with the Company ID using this API:

openmobile.ipass.com/moservices/rest/api/ipass/<companyid>/mo/endUser?action=suspendNow 

2. Input XML

<?xml version="1.0" encoding="UTF-8"?> 
<statusChangeRequest> 
 <endUserCredential> 
 <companyId>companyid</companyId> 
 <username>subscriber4@subcomp.com</username> 
 <email>subscriber4@subscriptioncompany.com</email> 
 </endUserCredential> 
</statusChangeRequest>

3. Reponse

The system should respond with an XML that looks like this:

<?xml version="1.0" encoding="UTF-8"?> 
<endUser> 
 <authType>HostedAuth</authType> 
 <company>companyid</company> 
 <createdBy>0</createdBy> 
 <createdTime>2013-12-13T23:01:57.751Z</createdTime> 
 <email>subscriber4@subscriptioncompany.com</email> 
 <fname>Favorite4</fname> 
 <isActive>0</isActive> 
 <lname>Subscriber4</lname> 
 <modifiedBy>38328</modifiedBy> 
 <modifiedTime>2013-12-13T23:21:36.898Z</modifiedTime> 
 <username>subscriber4@subcomp.com</username> 
 <departmentCode>Accounting</departmentCode> 
 <enablePortalLogin>false</enablePortalLogin> 
 <endUserId>129170</endUserId> 
 <endUserStatus>Suspended</endUserStatus> 
 <homeCountry>Country</homeCountry> 
 <startDate>MM/DD/YYYY</startDate> 
 <notifications> 
 <notification subscribe="true"><type>Activate</type></notification> 
 <notification subscribe="true"><type>Suspend</type></notification> 
 </notifications> 
</endUser> 

If a suspension template has not been configured, the user will not be notified of their suspension, they will simply not be able to connect anymore.

Retrieve User

1. Retrieve URL

openmobile.ipass.com/moservices/rest/api/ipass/<companyid>/mo/endUser/?action=retrieve&uname=enduserapitest1@company.com 

2. Input XML

There is no input XML field.

3. Response

The system should respond with an XML that looks like this:

<?xml version="1.0" encoding="UTF-8"?> 
<endUser> 
 <authType>HostedAuth</authType> 
 <company>companyid</company> 
 <createdBy>0</createdBy> 
 <createdTime>2013-12-13T23:01:58Z</createdTime> 
 <email>subscriber4@subscriptioncompany.com</email> 
 <fname>Favorite4</fname> 
 <isActive>0</isActive> 
 <lname>Subscriber4</lname> 
 <modifiedBy>38328</modifiedBy> 
 <modifiedTime>2013-12-13T23:24:02Z</modifiedTime> 
 <username>subscriber4@subcomp.com</username> 
 <departmentCode>Accounting</departmentCode> 
 <enablePortalLogin>false</enablePortalLogin> 
 <endUserId>129170</endUserId> 
 <endUserStatus>Suspended</endUserStatus> 
 <homeCountry>Country</homeCountry> 
 <startDate>MM/DD/YYYY</startDate> 
 <notifications> 
 <notification subscribe="true"><type>Activate</type></notification> 
 <notification subscribe="true"><type>Suspend</type></notification> 
 </notifications> 
</endUser>

Note on Future Versions

iPass makes its best efforts to keep the API backward compatible. We will minimize any changes to our APIs to avoid disruptions to scripts based on past versions of the API.

Go to: Portal Home > REST API Overview

 

©2015 iPass Inc. All rights reserved. Terms of Use