Managing Tenants with APIs

This section guides you through invoking and working with the TenantManagementService and the operations you can work within this service.

Invoking the admin service

TenantMgtAdminService is an admin service of the WSO2 Carbon platform. As admin services are secured to prevent anonymous invocations, you cannot view the WSDL of the admin service by default. Follow the steps below to view and invoke it:

Set the <HideAdminServiceWSDLs> element to false in <IS_HOME>/repository/conf/carbon.xml file.
```
<HideAdminServiceWSDLs>false</HideAdminServiceWSDLs>
```
Restart the Identity Server.
If you have started the server in default configurations, use the following URL in your browser to see the WSDL of the admin service: https://localhost:9443/services/TenantMgtAdminService?wsdl.

For more information on WSO2 admin services and how to invoke an admin service using either SoapUI or any other client program, see Calling Admin Services from Apps section in WSO2 Carbon documentation.

Operations included in the API

The following operations are available in the TenantManagement Service:

addTenant()

Description

Adds a new tenant.

Permission Level

/permission/protected/manage/monitor/tenants

Input Parameters

Parameter	Type	Description
tenantInfoBean	TenantInfoBean	Contains tenant related data
tenantInfoBean.tenantDomain	String	The domain name of the tenant
tenantInfoBean.active	Boolean	True - activate the tenant False- deactivate the tenant
tenantInfoBean.admin	String	The admin username
tenantInfoBean.adminPassword	String	The admin password
tenantInfoBean.createdDate	DateTime	The date and time that the tenant was created
tenantInfoBean.email	String	The email address of the tenant
tenantInfoBean.firstname	String	The first name of the tenant
tenantInfoBean.lastname	String	The last name of the tenant
tenantInfoBean.originatedService	String	-
tenantInfoBean.successKey	String	-
tenantInfoBean.tenantDomain	String	The tenant domain
tenantInfoBean.tenantId	Int	The tenant ID
tenantInfoBean.usagePlan	String	-

Request

Click here to see the request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://services.mgt.tenant.carbon.wso2.org" xmlns:xsd="http://beans.common.stratos.carbon.wso2.org/xsd">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:addTenant>
         <!--Optional:-->
         <ser:tenantInfoBean>
            <!--Optional:-->
            <xsd:active>?</xsd:active>
            <!--Optional:-->
            <xsd:admin>?</xsd:admin>
            <!--Optional:-->
            <xsd:adminPassword>?</xsd:adminPassword>
            <!--Optional:-->
            <xsd:createdDate>?</xsd:createdDate>
            <!--Optional:-->
            <xsd:email>?</xsd:email>
            <!--Optional:-->
            <xsd:firstname>?</xsd:firstname>
            <!--Optional:-->
            <xsd:lastname>?</xsd:lastname>
            <!--Optional:-->
            <xsd:originatedService>?</xsd:originatedService>
            <!--Optional:-->
            <xsd:successKey>?</xsd:successKey>
            <!--Optional:-->
            <xsd:tenantDomain>?</xsd:tenantDomain>
            <!--Optional:-->
            <xsd:tenantId>?</xsd:tenantId>
            <!--Optional:-->
            <xsd:usagePlan>?</xsd:usagePlan>
         </ser:tenantInfoBean>
      </ser:addTenant>
   </soapenv:Body>
</soapenv:Envelope>

Response

None

addSkeletonTenant()

Description

Adds a new tenant without userstore operations. The tenant will not be persisted in user store level and can be used to trigger post-tenant listeners without actuall creating the tenant.

Permission Level

/permission/protected/manage/monitor/tenants

Input Parameters

Parameter	Type	Description
tenantInfoBean	TenantInfoBean	Contains tenant related data
tenantInfoBean.tenantDomain	String	The domain name of the tenant
tenantInfoBean.active	Boolean	True - activate the tenant False- deactivate the tenant
tenantInfoBean.admin	String	The admin username
tenantInfoBean.adminPassword	String	The admin password
tenantInfoBean.createdDate	DateTime	The date and time that the tenant was created
tenantInfoBean.email	String	The email address of the tenant
tenantInfoBean.firstname	String	The first name of the tenant
tenantInfoBean.lastname	String	The last name of the tenant
tenantInfoBean.originatedService	String	-
tenantInfoBean.successKey	String	-
tenantInfoBean.tenantDomain	String	The tenant domain
tenantInfoBean.tenantId	Int	The tenant ID
tenantInfoBean.usagePlan	String	-

Request

Click here to see the request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://services.mgt.tenant.carbon.wso2.org" xmlns:xsd="http://beans.common.stratos.carbon.wso2.org/xsd">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:addSkeletonTenant>
         <!--Optional:-->
         <ser:tenantInfoBean>
            <!--Optional:-->
            <xsd:active>?</xsd:active>
            <!--Optional:-->
            <xsd:admin>?</xsd:admin>
            <!--Optional:-->
            <xsd:adminPassword>?</xsd:adminPassword>
            <!--Optional:-->
            <xsd:createdDate>?</xsd:createdDate>
            <!--Optional:-->
            <xsd:email>?</xsd:email>
            <!--Optional:-->
            <xsd:firstname>?</xsd:firstname>
            <!--Optional:-->
            <xsd:lastname>?</xsd:lastname>
            <!--Optional:-->
            <xsd:originatedService>?</xsd:originatedService>
            <!--Optional:-->
            <xsd:successKey>?</xsd:successKey>
            <!--Optional:-->
            <xsd:tenantDomain>?</xsd:tenantDomain>
            <!--Optional:-->
            <xsd:tenantId>?</xsd:tenantId>
            <!--Optional:-->
            <xsd:usagePlan>?</xsd:usagePlan>
         </ser:tenantInfoBean>
      </ser:addSkeletonTenant>
   </soapenv:Body>
</soapenv:Envelope>

Response

None

activateTenant()

Description

Activates an existing tenant.

Permission Level

/permission/protected/manage/modify/tenants

Input Parameters

Parameter	Type	Description
tenantDomain	String	The domain name of the tenant

Request

Click here to see the request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ser="http://services.mgt.tenant.carbon.wso2.org">
    <soapenv:Header/>
    <soapenv:Body>
        <ser:activateTenant>
            <!Optional:>
            <ser:tenantDomain>example.com</ser:tenantDomain>
        </ser:activateTenant>
    </soapenv:Body>
</soapenv:Envelope>

Response

Click here to see the response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <ns:activateTenantResponse xmlns:ns="http://services.mgt.tenant.carbon.wso2.org">
            <ns:return xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance" />
        </ns:activateTenantResponse>
    </soapenv:Body>
</soapenv:Envelope>

deactivateTenant()

Description

Deactivates an existing tenant.

Permission Level

/permission/protected/manage/modify/tenants

Input Parameters

Parameter	Type	Description
tenantDomain	String	The domain name of the tenant

Request

Click here to see the request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ser="http://services.mgt.tenant.carbon.wso2.org">
    <soapenv:Header/>
    <soapenv:Body>
        <ser:deactivateTenant>
            <!Optional:>
            <ser:tenantDomain>example.com</ser:tenantDomain>
        </ser:deactivateTenant>
    </soapenv:Body>
</soapenv:Envelope>

Response

Click here to see the response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <ns:deactivateTenantResponse xmlns:ns="http://services.mgt.tenant.carbon.wso2.org">
            <ns:return xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance" />
        </ns:deactivateTenantResponse>
    </soapenv:Body>
</soapenv:Envelope>

getTenant()

Description

Retrieves tenant details by domain name.

Permission Level

/permission/protected/manage/monitor/tenants

Input Parameters

Parameter	Type	Description
tenantInfoBean.tenantDomain	String	The domain name of the tenant

Request

Click here to see the request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ser="http://services.mgt.tenant.carbon.wso2.org">
    <soapenv:Header/>
    <soapenv:Body>
        <ser:getTenant>
            <!Optional:>
            <ser:tenantDomain>example.com</ser:tenantDomain>
        </ser:getTenant>
    </soapenv:Body>
</soapenv:Envelope>

Response

Click here to see the response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <ns:getTenantResponse xmlns:ns="http://services.mgt.tenant.carbon.wso2.org">
            <ns:return xsi:type="ax2582:TenantInfoBean" xmlns:ax2584="http://beans.mgt.tenant.carbon.wso2.org/xsd" xmlns:ax2582="http://beans.common.stratos.carbon.wso2.org/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance">
                <ax2582:active>true</ax2582:active>
                <ax2582:admin>test</ax2582:admin>
                <ax2582:adminPassword xsi:nil="true" />
                <ax2582:createdDate>20150213T07:27:17.543+05:30</ax2582:createdDate>
                <ax2582:email>test@example.com</ax2582:email>
                <ax2582:firstname>Test</ax2582:firstname>
                <ax2582:lastname>User</ax2582:lastname>
                <ax2582:originatedService xsi:nil="true" />
                <ax2582:successKey xsi:nil="true" />
                <ax2582:tenantDomain>example.com</ax2582:tenantDomain>
                <ax2582:tenantId>1</ax2582:tenantId>
                <ax2582:usagePlan/>
            </ns:return>
        </ns:getTenantResponse>
    </soapenv:Body>
</soapenv:Envelope>

retrievePaginatedPartialSearchTenants()

Description

Retrieves the tenant information based on the partial search.

Permission Level

/permission/protected/manage/monitor/tenants

Input Parameters

Parameter	Type	Description
tenant	String	Partial tenant domain name
pageNumber	Int	Page number

Request

Click here to see the request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://services.mgt.tenant.carbon.wso2.org">
    <soapenv:Header/>
    <soapenv:Body>
        <ser:retrievePaginatedPartialSearchTenants>
            <!Optional:>
            <ser:domain>.com</ser:domain>
            <!Optional:>
            <ser:pageNumber>1</ser:pageNumber>
        </ser:retrievePaginatedPartialSearchTenants>
    </soapenv:Body>
</soapenv:Envelope>

Response

Click here to see the response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <ns:retrievePaginatedPartialSearchTenantsResponse xmlns:ns="http://services.mgt.tenant.carbon.wso2.org">
            <ns:return xsi:type="ax2584:PaginatedTenantInfoBean" xmlns:ax2584="http://beans.mgt.tenant.carbon.wso2.org/xsd" xmlns:ax2582="http://beans.common.stratos.carbon.wso2.org/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance">
                <ax2584:numberOfPages>1</ax2584:numberOfPages>
                <ax2584:tenantInfoBeans xsi:type="ax2582:TenantInfoBean">
                    <ax2582:active>true</ax2582:active>
                    <ax2582:admin xsi:nil="true" />
                    <ax2582:adminPassword xsi:nil="true" />
                    <ax2582:createdDate>20150213T07:27:17.543+05:30</ax2582:createdDate>
                    <ax2582:email>test@example.com</ax2582:email>
                    <ax2582:firstname xsi:nil="true" />
                    <ax2582:lastname xsi:nil="true" />
                    <ax2582:originatedService xsi:nil="true" />
                    <ax2582:successKey xsi:nil="true" />
                    <ax2582:tenantDomain>example.com</ax2582:tenantDomain>
                    <ax2582:tenantId>1</ax2582:tenantId>
                    <ax2582:usagePlan xsi:nil="true" />
                </ax2584:tenantInfoBeans>
            </ns:return>
        </ns:retrievePaginatedPartialSearchTenantsResponse>
    </soapenv:Body>
</soapenv:Envelope>

retrievePaginatedTenants()

Description

Activates an existing tenant.

Permission Level

/permission/protected/manage/monitor/tenants

Input Parameters

Parameter	Type	Description
pageNumber	Int	Page number

Request

Click here to see the request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ser="http://services.mgt.tenant.carbon.wso2.org">
    <soapenv:Header/>
    <soapenv:Body>
        <ser:retrievePaginatedTenants>
            <!Optional:>
            <ser:pageNumber>1</ser:pageNumber>
        </ser:retrievePaginatedTenants>
    </soapenv:Body>
</soapenv:Envelope>

Response

Click here to see the response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <ns:retrievePaginatedTenantsResponse xmlns:ns="http://services.mgt.tenant.carbon.wso2.org">
            <ns:return xsi:type="ax2584:PaginatedTenantInfoBean" xmlns:ax2584="http://beans.mgt.tenant.carbon.wso2.org/xsd" xmlns:ax2582="http://beans.common.stratos.carbon.wso2.org/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance">
                <ax2584:numberOfPages>1</ax2584:numberOfPages>
                <ax2584:tenantInfoBeans xsi:type="ax2582:TenantInfoBean">
                    <ax2582:active>true</ax2582:active>
                    <ax2582:admin xsi:nil="true" />
                    <ax2582:adminPassword xsi:nil="true" />
                    <ax2582:createdDate>20150213T07:27:17.543+05:30</ax2582:createdDate>
                    <ax2582:email>test@example.com</ax2582:email>
                    <ax2582:firstname xsi:nil="true" />
                    <ax2582:lastname xsi:nil="true" />
                    <ax2582:originatedService xsi:nil="true" />
                    <ax2582:successKey xsi:nil="true" />
                    <ax2582:tenantDomain>example.com</ax2582:tenantDomain>
                    <ax2582:tenantId>1</ax2582:tenantId>
                    <ax2582:usagePlan xsi:nil="true" />
                </ax2584:tenantInfoBeans>
            </ns:return>
        </ns:retrievePaginatedTenantsResponse>
    </soapenv:Body>
</soapenv:Envelope>

retrievePartialSearchTenants()

Description

Retrieves all tenants that contain the specified part of the domain name (e.g., All tenant domains with ‘.com’)

Permission Level

/permission/protected/manage/monitor/tenants

Input Parameters

Parameter	Type	Description
domain	String	Partial tenant domain name

Request

Click here to see the request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://services.mgt.tenant.carbon.wso2.org">
    <soapenv:Header/>
    <soapenv:Body>
        <ser:retrievePartialSearchTenants>
            <!Optional:>
            <ser:domain>.com</ser:domain>
        </ser:retrievePartialSearchTenants>
    </soapenv:Body>
</soapenv:Envelope>

Response

Click here to see the response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <ns:retrievePartialSearchTenantsResponse xmlns:ns="http://services.mgt.tenant.carbon.wso2.org" xmlns:ax2584="http://beans.mgt.tenant.carbon.wso2.org/xsd" xmlns:ax2582="http://beans.common.stratos.carbon.wso2.org/xsd">
            <ns:return xsi:type="ax2582:TenantInfoBean" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance">
                <ax2582:active>true</ax2582:active>
                <ax2582:admin xsi:nil="true" />
                <ax2582:adminPassword xsi:nil="true" />
                <ax2582:createdDate>20150213T07:27:17.543+05:30</ax2582:createdDate>
                <ax2582:email>test@example.com</ax2582:email>
                <ax2582:firstname xsi:nil="true" />
                <ax2582:lastname xsi:nil="true" />
                <ax2582:originatedService xsi:nil="true" />
                <ax2582:successKey xsi:nil="true" />
                <ax2582:tenantDomain>example.com</ax2582:tenantDomain>
                <ax2582:tenantId>1</ax2582:tenantId>
                <ax2582:usagePlan xsi:nil="true" />
            </ns:return>
        </ns:retrievePartialSearchTenantsResponse>
    </soapenv:Body>
</soapenv:Envelope>

retrieveTenants()

Description	Retrieves all tenants.
Permission Level	/permission/protected/manage/monitor/tenants
Input Parameters	None
Request	Click here to see the request <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://services.mgt.tenant.carbon.wso2.org"> <soapenv:Header/> <soapenv:Body> <ser:retrieveTenants/> </soapenv:Body> </soapenv:Envelope>
Response	Click here to see the response <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Body> <ns:retrieveTenantsResponse xmlns:ns="http://services.mgt.tenant.carbon.wso2.org" xmlns:ax2584="http://beans.mgt.tenant.carbon.wso2.org/xsd" xmlns:ax2582="http://beans.common.stratos.carbon.wso2.org/xsd"> <ns:return xsi:type="ax2582:TenantInfoBean" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance"> <ax2582:active>true</ax2582:active> <ax2582:admin xsi:nil="true" /> <ax2582:adminPassword xsi:nil="true" /> <ax2582:createdDate>20150213T07:27:17.543+05:30</ax2582:createdDate> <ax2582:email>test@example.com</ax2582:email> <ax2582:firstname xsi:nil="true" /> <ax2582:lastname xsi:nil="true" /> <ax2582:originatedService xsi:nil="true" /> <ax2582:successKey xsi:nil="true" /> <ax2582:tenantDomain>example.com</ax2582:tenantDomain> <ax2582:tenantId>1</ax2582:tenantId> <ax2582:usagePlan xsi:nil="true" /> </ns:return> </ns:retrieveTenantsResponse> </soapenv:Body> </soapenv:Envelope>

updateTenant()

Description

Updates the tenant details based on the specified tenantId. To update the password, the respective admin name should be included.

Permission Level

/permission/protected/manage/modify/tenants

Input Parameters

Parameter	Type	Description
tenantInfoBean	TenantInfoBean	Contains tenant related data
tenantInfoBean.tenantDomain	String	The domain name of the tenant
tenantInfoBean.active	Boolean	True - activate the tenant False- deactivate the tenant
tenantInfoBean.admin	String	The admin username
tenantInfoBean.adminPassword	String	The admin password
tenantInfoBean.createdDate	DateTime	The date and time that the tenant was created
tenantInfoBean.email	String	The email address of the tenant
tenantInfoBean.firstname	String	The first name of the tenant
tenantInfoBean.lastname	String	The last name of the tenant
tenantInfoBean.originatedService	String	-
tenantInfoBean.successKey	String	-
tenantInfoBean.tenantDomain	String	The tenant domain
tenantInfoBean.tenantId	Int	The tenant ID
tenantInfoBean.usagePlan	String	-

Request

Click here to see the request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ser="http://services.mgt.tenant.carbon.wso2.org" xmlns:xsd="http://beans.common.stratos.carbon.wso2.org/xsd">
    <soapenv:Header/>
    <soapenv:Body>
        <ser:updateTenant>
            <!Optional:>
            <ser:tenantInfoBean>
                <!Optional:>
                <xsd:active>true</xsd:active>
                <!Optional:>
                <xsd:admin>test</xsd:admin>
                <!Optional:>
                <xsd:adminPassword>testpw</xsd:adminPassword>
                <!Optional:>
                <xsd:createdDate></xsd:createdDate>
                <!Optional:>
                <xsd:email>testuser@example.com</xsd:email>
                <!Optional:>
                <xsd:firstname>test</xsd:firstname>
                <!Optional:>
                <xsd:lastname>user</xsd:lastname>
                <!Optional:>
                <xsd:originatedService></xsd:originatedService>
                <!Optional:>
                <xsd:successKey></xsd:successKey>
                <!Optional:>
                <xsd:tenantDomain>example.com</xsd:tenantDomain>
                <!Optional:>
                <xsd:tenantId>1</xsd:tenantId>
                <!Optional:>
                <xsd:usagePlan></xsd:usagePlan>
            </ser:tenantInfoBean>
        </ser:updateTenant>
    </soapenv:Body>
</soapenv:Envelope>

Response

Click here to see the response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <ns:updateTenantResponse xmlns:ns="http://services.mgt.tenant.carbon.wso2.org">
            <ns:return xsi:nil="true" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance" />
        </ns:updateTenantResponse>
    </soapenv:Body>
</soapenv:Envelope>